@syscore/ui-library 1.27.3 → 2.0.0-beta-publish-workflow-beta.2

package/client/ui/Layout/LayoutHeader.stories.tsx

@@ -0,0 +1,104 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import {
+  HStack,
+  Layout,
+  LayoutContent,
+  LayoutHeader,
+  VStack,
+} from "../../components/ui/layout";
+import { ButtonV01 } from "../../components/ui/button-v01";
+import { Text } from "../../components/ui/typography";
+import { ShellFrame } from "./demo";
+
+const meta = {
+  title: "Components/Layout/LayoutHeader",
+  component: LayoutHeader,
+  tags: ["autodocs"],
+  parameters: {
+    layout: "padded",
+    docs: {
+      description: {
+        component: [
+          "Top region of `Layout`. Put `HStack` inside for title + actions, or a `VStack` for a second row (breadcrumb, tabs).",
+          "",
+          'Pinned by Layout’s grid while `height="fill"`. Not CSS `position: sticky` — with `height="auto"` the header scrolls away.',
+          "",
+          "Horizontal inset comes from `Layout padding`; vertical inset from `--layout-chrome-padding-block`. Height floor is `--layout-header-min-height`.",
+          "",
+          "```tsx",
+          "<LayoutHeader>",
+          '  <HStack justify="between" align="center" width="100%">',
+          "    <Text>Title</Text>",
+          "  </HStack>",
+          "</LayoutHeader>",
+          "```",
+          "",
+          "Takes no `className` or `style` — sizing comes from `Layout` and `--layout-*` variables, so a design-system change reaches every app.",
+          "",
+        ].join("\n"),
+      },
+    },
+  },
+  argTypes: {
+    as: { control: "select", options: ["header", "div"] },
+  },
+} satisfies Meta<typeof LayoutHeader>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  args: { as: "header" },
+  render: (args) => (
+    <ShellFrame height={280}>
+      <Layout>
+        <LayoutHeader {...args}>
+          <HStack justify="between" align="center" width="100%">
+            <Text variant="heading-xxsmall">Page title</Text>
+            <ButtonV01
+              typeVariant="utility"
+              appearance="solid"
+              hierarchy="secondary"
+              size="medium"
+            >
+              Edit
+            </ButtonV01>
+          </HStack>
+        </LayoutHeader>
+        <LayoutContent>
+          <Text variant="body-small">Main</Text>
+        </LayoutContent>
+      </Layout>
+    </ShellFrame>
+  ),
+};
+
+export const TwoRows: Story = {
+  name: "Title and breadcrumb",
+  args: { as: "header" },
+  render: (args) => (
+    <ShellFrame height={280}>
+      <Layout>
+        <LayoutHeader {...args}>
+          <VStack gap="xs" width="100%">
+            <Text variant="body-small">Projects / North campus</Text>
+            <HStack justify="between" align="center" width="100%">
+              <Text variant="heading-xxsmall">Building audit</Text>
+              <ButtonV01
+                typeVariant="utility"
+                appearance="solid"
+                context="confirm"
+                size="medium"
+              >
+                Save
+              </ButtonV01>
+            </HStack>
+          </VStack>
+        </LayoutHeader>
+        <LayoutContent>
+          <Text variant="body-small">Main</Text>
+        </LayoutContent>
+      </Layout>
+    </ShellFrame>
+  ),
+};

package/client/ui/Layout/LayoutPanel.stories.tsx

@@ -0,0 +1,143 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import {
+  HStack,
+  Layout,
+  LayoutContent,
+  LayoutHeader,
+  LayoutPanel,
+  SPACE_NAMES,
+  VStack,
+} from "../../components/ui/layout";
+import { Text } from "../../components/ui/typography";
+import { ShellFrame } from "./demo";
+
+const meta = {
+  title: "Components/Layout/LayoutPanel",
+  component: LayoutPanel,
+  tags: ["autodocs"],
+  parameters: {
+    layout: "padded",
+    docs: {
+      description: {
+        component: [
+          'Sidebar region of `Layout`. `placement="start"` is left in LTR; `"end"` is right.',
+          "",
+          "Padded by its own `padding` (default `xl`, `--layout-panel-padding`) — not by `Layout padding`.",
+          "",
+          "`width` is a named size backed by `--layout-panel-width-*`: `narrow` 12.5rem, `default` 17.5rem, `wide` 22.5rem. No px — change the variable and every panel in every app moves.",
+          "",
+          "Below 768px panels stack full-width above/below content.",
+          "",
+          "```tsx",
+          "<LayoutPanel>Nav</LayoutPanel>",
+          '<LayoutPanel placement="end" width="narrow">Inspector</LayoutPanel>',
+          "```",
+          "",
+          "Takes no `className` or `style` — sizing comes from `Layout` and `--layout-*` variables, so a design-system change reaches every app.",
+          "",
+          "`width` and `padding` show no default in the table below because theirs live in CSS: `--layout-panel-width-default` and `--layout-panel-padding`. Leave them unset to inherit.",
+          "",
+        ].join("\n"),
+      },
+    },
+  },
+  argTypes: {
+    placement: { control: "select", options: ["start", "end"] },
+    width: { control: "select", options: ["narrow", "default", "wide"] },
+    padding: { control: "select", options: [...SPACE_NAMES] },
+    isScrollable: { control: "boolean" },
+    as: { control: "select", options: ["aside", "nav", "div"] },
+  },
+  args: {
+    placement: "start",
+    isScrollable: true,
+  },
+} satisfies Meta<typeof LayoutPanel>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  name: "Start",
+  render: (args) => (
+    <ShellFrame height={320}>
+      <Layout>
+        <LayoutHeader>
+          <HStack justify="between" align="center" width="100%">
+            <Text variant="heading-xxsmall">Start panel</Text>
+          </HStack>
+        </LayoutHeader>
+        <LayoutPanel {...args}>
+          <VStack gap="sm">
+            <Text variant="body-small">Dashboard</Text>
+            <Text variant="body-small">Projects</Text>
+            <Text variant="body-small">Settings</Text>
+          </VStack>
+        </LayoutPanel>
+        <LayoutContent>
+          <VStack gap="sm">
+            <Text variant="heading-xsmall">Main</Text>
+            <Text variant="body-small">
+              Nav sits in the start panel. Try width and padding in Controls.
+            </Text>
+          </VStack>
+        </LayoutContent>
+      </Layout>
+    </ShellFrame>
+  ),
+};
+
+export const End: Story = {
+  args: { placement: "end", width: "narrow" },
+  render: (args) => (
+    <ShellFrame height={320}>
+      <Layout>
+        <LayoutHeader>
+          <HStack justify="between" align="center" width="100%">
+            <Text variant="heading-xxsmall">End panel</Text>
+          </HStack>
+        </LayoutHeader>
+        <LayoutContent>
+          <VStack gap="sm">
+            <Text variant="heading-xsmall">Main</Text>
+            <Text variant="body-small">Inspector sits in the end panel.</Text>
+          </VStack>
+        </LayoutContent>
+        <LayoutPanel {...args}>
+          <VStack gap="sm">
+            <Text variant="overline-small">Inspector</Text>
+            <Text variant="body-small">Details</Text>
+          </VStack>
+        </LayoutPanel>
+      </Layout>
+    </ShellFrame>
+  ),
+};
+
+export const LongNav: Story = {
+  name: "Long nav scrolls",
+  args: { isScrollable: true },
+  render: (args) => (
+    <ShellFrame height={320}>
+      <Layout>
+        <LayoutHeader>
+          <HStack justify="between" align="center" width="100%">
+            <Text variant="heading-xxsmall">Scrollable panel</Text>
+          </HStack>
+        </LayoutHeader>
+        <LayoutPanel {...args}>
+          <VStack gap="sm">
+            {Array.from({ length: 16 }, (_, i) => (
+              <Text key={i} variant="body-small">
+                Nav item {i + 1}
+              </Text>
+            ))}
+          </VStack>
+        </LayoutPanel>
+        <LayoutContent>
+          <Text variant="body-small">The start panel scrolls on its own.</Text>
+        </LayoutContent>
+      </Layout>
+    </ShellFrame>
+  ),
+};

package/client/ui/Layout/Positioned.stories.tsx

@@ -0,0 +1,113 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import { Positioned, VStack } from "../../components/ui/layout";
+import { Text } from "../../components/ui/typography";
+import { DemoBox, LAYOUT_DOCS_RULE } from "./demo";
+import { hiddenArgs } from "./controls";
+
+const meta = {
+  title: "Components/Layout/Positioned",
+  component: Positioned,
+  tags: ["autodocs"],
+  parameters: {
+    layout: "padded",
+    docs: {
+      description: {
+        component: [
+          "CSS positioning without Tailwind `absolute top-0`. Badges, overlays, sticky bars.",
+          "",
+          LAYOUT_DOCS_RULE,
+          "",
+          "```tsx",
+          `import { Positioned } from "@syscore/ui-library"`,
+          "",
+          '<Positioned position="relative">',
+          '  <Positioned position="absolute" top={8} right={8}>',
+          "    <Badge />",
+          "  </Positioned>",
+          "</Positioned>",
+          "```",
+          "",
+          "`fill` is shorthand for `inset: 0` — an overlay covering its positioned parent. `inset` sets all four sides at once.",
+          "",
+          "Offsets are raw CSS lengths, not tokens: a number is treated as px. Keep them small and incidental — anything structural belongs on a stack or grid.",
+        ].join("\n"),
+      },
+    },
+  },
+  argTypes: {
+    ...hiddenArgs,
+    position: {
+      control: "inline-radio",
+      options: ["relative", "absolute", "fixed", "sticky"],
+    },
+    fill: { control: "boolean" },
+    zIndex: { control: "number" },
+  },
+  args: { position: "absolute", top: 8, right: 8 },
+} satisfies Meta<typeof Positioned>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  name: "Corner badge",
+  render: (args) => (
+    <Positioned position="relative">
+      <DemoBox label="Positioned parent" tall />
+      <Positioned {...args}>
+        <Text variant="overline-small">NEW</Text>
+      </Positioned>
+    </Positioned>
+  ),
+};
+
+export const Overlay: Story = {
+  args: { position: "absolute", fill: true, top: undefined, right: undefined },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          "`fill` covers the positioned parent — loading and disabled states.",
+      },
+    },
+  },
+  render: (args) => (
+    <Positioned position="relative">
+      <DemoBox label="Content underneath" tall />
+      <Positioned {...args}>
+        <VStack
+          align="center"
+          justify="center"
+          height="100%"
+          className="sb-fill"
+        >
+          <Text variant="body-small">Overlay</Text>
+        </VStack>
+      </Positioned>
+    </Positioned>
+  ),
+};
+
+export const Sticky: Story = {
+  args: { position: "sticky", top: 0, right: undefined, zIndex: 1 },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          "A sticky bar inside a scrolling region. Scroll the box to pin it.",
+      },
+    },
+  },
+  render: (args) => (
+    <VStack height={240} isScrollable gap="sm" width="100%" maxWidth={480}>
+      <Positioned {...args}>
+        <VStack className="sb-fill" padding="sm">
+          <Text variant="body-small">Sticky header</Text>
+        </VStack>
+      </Positioned>
+      {Array.from({ length: 10 }, (_, i) => (
+        <DemoBox key={i} label={`Row ${i + 1}`} />
+      ))}
+    </VStack>
+  ),
+};

package/client/ui/Layout/Section.stories.tsx

@@ -0,0 +1,84 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import { Section, VStack } from "../../components/ui/layout";
+import { Text } from "../../components/ui/typography";
+import { LAYOUT_DOCS_RULE } from "./demo";
+import { hiddenArgs } from "./controls";
+
+const meta = {
+  title: "Components/Layout/Section",
+  component: Section,
+  tags: ["autodocs"],
+  parameters: {
+    layout: "padded",
+    docs: {
+      description: {
+        component: [
+          "Vertical padding between page sections. Pair with `Center` or `Layout contentWidth` for max-width.",
+          "",
+          LAYOUT_DOCS_RULE,
+          "",
+          "```tsx",
+          `import { Section } from "@syscore/ui-library"`,
+          "",
+          '<Section padding="lg">',
+          "  <h1>Features</h1>",
+          "</Section>",
+          "```",
+          "",
+          "Padding is responsive — it grows at 768px, so a section breathes on desktop without a breakpoint prop.",
+          "",
+          "| `padding` | Mobile | Desktop |",
+          "|-----------|--------|---------|",
+          "| `sm` | 2rem | 3rem |",
+          "| `md` | 3rem | 4rem |",
+          "| `lg` (default) | 4rem | 6rem |",
+          "| `xl` | 6rem | 8rem |",
+          "| `none` | 0 | 0 |",
+        ].join("\n"),
+      },
+    },
+  },
+  argTypes: {
+    ...hiddenArgs,
+    padding: {
+      control: "inline-radio",
+      options: ["none", "sm", "md", "lg", "xl"],
+    },
+  },
+  args: { padding: "lg" },
+} satisfies Meta<typeof Section>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  render: (args) => (
+    <Section {...args} className="sb-fill">
+      <Text variant="body-small">
+        Section padding=&quot;{args.padding}&quot;
+      </Text>
+    </Section>
+  ),
+};
+
+export const Scale: Story = {
+  name: "All sizes",
+  parameters: {
+    controls: { disable: true },
+    docs: {
+      description: {
+        story:
+          "Every step side by side. Resize past 768px to see each one grow.",
+      },
+    },
+  },
+  render: () => (
+    <VStack gap="xs" width="100%">
+      {(["sm", "md", "lg", "xl"] as const).map((padding) => (
+        <Section key={padding} padding={padding} className="sb-fill">
+          <Text variant="body-small">padding=&quot;{padding}&quot;</Text>
+        </Section>
+      ))}
+    </VStack>
+  ),
+};

package/client/ui/Layout/ShowHide.stories.tsx

@@ -0,0 +1,99 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import { Hide, Show, VStack } from "../../components/ui/layout";
+import { Text } from "../../components/ui/typography";
+import { DemoBox, LAYOUT_DOCS_RULE } from "./demo";
+import { hiddenArgs } from "./controls";
+
+const meta = {
+  title: "Components/Layout/ShowAndHide",
+  component: Show,
+  subcomponents: { Hide },
+  tags: ["autodocs"],
+  parameters: {
+    layout: "padded",
+    docs: {
+      description: {
+        component: [
+          "Responsive visibility without Tailwind `hidden md:block`. `Show` renders only inside the range; `Hide` renders everywhere except it.",
+          "",
+          LAYOUT_DOCS_RULE,
+          "",
+          "```tsx",
+          `import { Show, Hide } from "@syscore/ui-library"`,
+          "",
+          '<Show above="md"><DesktopNav /></Show>',
+          '<Hide above="md"><MenuButton /></Hide>',
+          "```",
+          "",
+          "| Breakpoint | Min width |",
+          "|------------|-----------|",
+          "| `sm` | 640px |",
+          "| `md` | 768px |",
+          "| `lg` | 1024px |",
+          "| `xl` | 1280px |",
+          "",
+          "**These toggle CSS `display`, they do not unmount.** The children still render and still run their effects — for genuinely mobile-only work, branch in JS instead.",
+          "",
+          "Resize the canvas to see the boxes below swap.",
+        ].join("\n"),
+      },
+    },
+  },
+  argTypes: {
+    ...hiddenArgs,
+    above: {
+      control: "inline-radio",
+      options: [undefined, "sm", "md", "lg", "xl"],
+    },
+    below: {
+      control: "inline-radio",
+      options: [undefined, "sm", "md", "lg", "xl"],
+    },
+  },
+  args: { above: "md" },
+} satisfies Meta<typeof Show>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const ShowAbove: Story = {
+  name: "Show above a breakpoint",
+  render: (args) => (
+    <Show {...args}>
+      <DemoBox label={`Visible above ${args.above ?? "—"}`} tall />
+    </Show>
+  ),
+};
+
+export const HideAbove: Story = {
+  name: "Hide above a breakpoint",
+  render: (args) => (
+    <Hide {...args}>
+      <DemoBox label={`Hidden above ${args.above ?? "—"}`} tall />
+    </Hide>
+  ),
+};
+
+export const SwapPair: Story = {
+  name: "Swap at a breakpoint",
+  parameters: {
+    controls: { disable: true },
+    docs: {
+      description: {
+        story:
+          "The usual pairing: a desktop treatment and a compact one, each wrapped so exactly one shows.",
+      },
+    },
+  },
+  render: () => (
+    <VStack gap="sm" width="100%">
+      <Show above="md">
+        <DemoBox label="Wide layout (≥ 768px)" tall />
+      </Show>
+      <Hide above="md">
+        <DemoBox label="Compact layout (< 768px)" tall />
+      </Hide>
+      <Text variant="body-small">Drag the canvas edge across 768px.</Text>
+    </VStack>
+  ),
+};

package/client/ui/Layout/Spacer.stories.tsx

@@ -0,0 +1,149 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import {
+  HStack,
+  SPACE_NAMES,
+  SPACE_SCALE,
+  Spacer,
+  VStack,
+  type SpaceName,
+} from "../../components/ui/layout";
+import { DemoBox, LAYOUT_DOCS_RULE } from "./demo";
+
+const meta = {
+  title: "Components/Layout/Spacer",
+  component: Spacer,
+  tags: ["autodocs"],
+  parameters: {
+    layout: "padded",
+    docs: {
+      description: {
+        component: [
+          "Named empty space from the design-system scale. Change `--space-*` in CSS and every app updates.",
+          "Even spacing belongs on `HStack` / `VStack` `gap` — not a Spacer between every item.",
+          "",
+          LAYOUT_DOCS_RULE,
+          "",
+          "```tsx",
+          `import { Spacer, VStack, HStack } from "@syscore/ui-library"`,
+          "",
+          "<VStack gap={0}>",
+          "  <Title />",
+          `  <Spacer space="xl" />`,
+          "  <Body />",
+          "</VStack>",
+          "",
+          '<HStack gap="md">',
+          "  <Logo />",
+          "  <Spacer flex />",
+          "  <Actions />",
+          "</HStack>",
+          "```",
+          "",
+          "| Name | px |",
+          "|------|----|",
+          ...SPACE_NAMES.map(
+            (name) => `| \`${name}\` | ${SPACE_SCALE[name]} |`,
+          ),
+          "",
+          "`flex` ignores `space` and `axis` and grows to eat the leftover room in a stack — the way to push actions to the far end of a row.",
+        ].join("\n"),
+      },
+    },
+  },
+  argTypes: {
+    space: { control: "select", options: [...SPACE_NAMES] },
+    axis: { control: "inline-radio", options: ["vertical", "horizontal"] },
+    flex: { control: "boolean" },
+    size: { table: { disable: true } },
+  },
+  args: {
+    space: "md",
+    axis: "vertical",
+    flex: false,
+  },
+} satisfies Meta<typeof Spacer>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  parameters: {
+    docs: {
+      source: {
+        code: `<VStack gap={0}>
+  <Item />
+  <Spacer space="xl" />
+  <Item />
+</VStack>`,
+      },
+    },
+  },
+  render: (args) => (
+    <VStack gap={0} maxWidth={384}>
+      <DemoBox label="Above" />
+      <Spacer {...args} className="sb-spacer-fill" />
+      <DemoBox label="Below" />
+    </VStack>
+  ),
+};
+
+export const Vertical: Story = {
+  args: { space: "2xl", axis: "vertical" },
+  render: (args) => (
+    <VStack gap={0} maxWidth={384}>
+      <DemoBox label="Title" />
+      <Spacer {...args} className="sb-spacer-fill" />
+      <DemoBox label="Body" />
+    </VStack>
+  ),
+};
+
+export const Horizontal: Story = {
+  args: { space: "xl", axis: "horizontal" },
+  render: (args) => (
+    <HStack gap={0} align="center">
+      <DemoBox label="Left" />
+      <Spacer
+        {...args}
+        className="sb-spacer-fill"
+        style={{ alignSelf: "stretch" }}
+      />
+      <DemoBox label="Right" />
+    </HStack>
+  ),
+};
+
+export const Flex: Story = {
+  args: { flex: true },
+  render: (args) => (
+    <HStack gap="sm" width="100%" maxWidth={480}>
+      <DemoBox label="Logo" />
+      <Spacer {...args} className="sb-spacer-fill" />
+      <DemoBox label="Actions" />
+    </HStack>
+  ),
+};
+
+export const Scale: Story = {
+  name: "All spaces",
+  render: () => (
+    <VStack gap="md" maxWidth={480}>
+      {SPACE_NAMES.map((name: SpaceName) => (
+        <VStack key={name} gap="3xs">
+          <span className="sb-caption">
+            {name} · {SPACE_SCALE[name]}px
+          </span>
+          <Spacer space={name} axis="vertical" className="sb-spacer-fill" />
+        </VStack>
+      ))}
+    </VStack>
+  ),
+  parameters: {
+    controls: { disable: true },
+    docs: {
+      description: {
+        story: "Every step on the scale, rendered at true size.",
+      },
+    },
+  },
+};