Update Layout

docs/local-cfpb-ds.md

@@ -0,0 +1,47 @@
+# Pointing design-system-react at a local `@cfpb/cfpb-design-system`
+
+Use this when you have the [cfpb/design-system](https://github.com/cfpb/design-system) repo cloned next to this repo and want Storybook/tests to use your branch (e.g. layout fixes) before a release.
+
+## Layout
+
+Assume sibling directories:
+
+```text
+projects/
+  design-system/          # monorepo root; package lives in packages/cfpb-design-system/
+  design-system-react/    # this repo
+```
+
+If your paths differ, adjust the `portal:` URL below.
+
+## Yarn (Berry)
+
+In **design-system-react** `package.json`, temporarily set the devDependency to the **portal** protocol (live symlink to source):
+
+```json
+"@cfpb/cfpb-design-system": "portal:../design-system/packages/cfpb-design-system"
+```
+
+Then from **design-system-react**:
+
+```bash
+yarn install
+yarn storybook
+# optional
+yarn test
+```
+
+`portal:` keeps the dependency wired to your clone so SCSS/JS changes in `design-system` show up after save (no publish step).
+
+## After you’re done
+
+1. Remove the `portal:` line and restore the published version (e.g. `"5.3.2"`).
+2. Run `yarn install` again.
+
+## Optional: trim duplicate Layout CSS here
+
+`src/components/Layout/layout.scss` in this repo duplicates some rules that belong in the DS once your PR ships. After you adopt a released `@cfpb/cfpb-design-system` that includes the layout fix, consider removing the overlapping blocks from `layout.scss` so overrides stay minimal.
+
+## Alternative: `yarn link`
+
+From `design-system/packages/cfpb-design-system` you can `yarn link`, then in design-system-react `yarn link @cfpb/cfpb-design-system`. Portal is usually simpler in a Yarn workspaces/monorepo workflow.

src/components/Layout/layout-stories-shared.tsx

@@ -0,0 +1,54 @@
+import type { ReactElement } from 'react';
+import { Layout } from '~/src/index';
+import type { LayoutMainProperties } from './layout-main';
+
+export const LAYOUT_DOCS_SOURCE =
+  'https://cfpb.github.io/design-system/development/main-content-and-sidebars';
+
+export const LAYOUT_DOCS = {
+  component: `Use \`Layout.Main\`, \`Layout.Wrapper\`, \`Layout.Content\`, and \`Layout.Sidebar\` together to structure page content and optional sidebars.
+
+Main is the container for all content within a layout and configures column structure (\`layout\`) and whether the sidebar bleeds to the window edge. Content is the main body of the page. Wrapper positions content and sidebar columns. Sidebar is a vertical region beside the main content.
+
+Source: ${LAYOUT_DOCS_SOURCE}`,
+} as const;
+
+export const LAYOUT_EXAMPLE_LOREM =
+  'Lorem ipsum, dolor sit amet consectetur adipisicing elit. Quaerat alias eum ut officiis optio similique explicabo cupiditate architecto voluptatem nostrum recusandae, eaque consectetur iure, veritatis eos, mollitia possimus error earum?';
+
+export const LayoutExampleContent = (): ReactElement => (
+  <Layout.Content>
+    <h1>Content</h1>
+    <p>{LAYOUT_EXAMPLE_LOREM}</p>
+  </Layout.Content>
+);
+
+export const LayoutExampleSidebar = (): ReactElement => (
+  <Layout.Sidebar>
+    <div>
+      <h2>Sidebar</h2>
+      <ul>
+        <li>Item 1</li>
+        <li>Item 2</li>
+        <li>Item 3</li>
+      </ul>
+    </div>
+  </Layout.Sidebar>
+);
+
+export const renderLayoutTwoColumnExample = ({
+  layout = '2-1',
+}: {
+  layout?: LayoutMainProperties['layout'];
+}): ReactElement => {
+  const contentNode = LayoutExampleContent();
+  const sidebarNode = LayoutExampleSidebar();
+  const columnChildren =
+    layout === '1-3' ? [sidebarNode, contentNode] : [contentNode, sidebarNode];
+
+  return (
+    <Layout.Main layout={layout}>
+      <Layout.Wrapper>{columnChildren}</Layout.Wrapper>
+    </Layout.Main>
+  );
+};