@sableui/react 0.6.2 → 0.7.1

package/dist/components/workspace/workspace.meta.js

@@ -0,0 +1,183 @@
+// src/components/workspace/workspace.meta.ts
+var workspaceMeta = {
+  name: "Workspace",
+  summary: "The shell for a tool: a fixed viewport partitioned into independently scrolling regions, with a compact density scope, a skip link, and a canvas landmark.",
+  keywords: [
+    "workspace",
+    "tool",
+    "editor",
+    "shell",
+    "frame",
+    "canvas",
+    "chrome",
+    "panels",
+    "density",
+    "viewport"
+  ],
+  usage: {
+    description: 'Use Workspace as the outer frame for a tool \u2014 an editor, a console, a canvas app. It owns the viewport, scopes the compact control density, and guarantees a skip link plus a main landmark on the canvas. Reach for AppShell instead for page-register products: it is built around a scrolling document, where a workspace is built around a fixed one. Workspace fills the viewport (h-dvh) by design; to embed one in a page (a docs preview, a modal-sized demo), wrap it in a bounded container and pass className="h-full".',
+    bestPractices: [
+      {
+        guidance: "do",
+        description: "Put a PanelGroup in the body and a WorkspaceCanvas inside it, so panels are aside chrome and the work surface is the main landmark."
+      },
+      {
+        guidance: "do",
+        description: "Let each panel own its scrolling. The shell never scrolls, and the canvas clips rather than scrolls \u2014 panning is the viewport's job."
+      },
+      {
+        guidance: "do",
+        description: "Keep the density scope at compact unless you have a specific reason; the workspace register's measured control ladder is what makes tool chrome read as tool chrome."
+      },
+      {
+        guidance: "dont",
+        description: "Nest a Region or Page inside it to set a width. Region caps are a page-register idea; a workspace is edge-to-edge and its panels are fixed-width chrome outside the content grid."
+      },
+      {
+        guidance: "dont",
+        description: "Hardcode a control height (h-[32px]). CI rejects it (raw-control-height); read the ladder instead, e.g. h-(--control-sm), so the density scope can size it."
+      },
+      {
+        guidance: "dont",
+        description: "Put a Card in the chrome. Use PanelSection \u2014 a card inside a narrow panel spends its border and inset on nothing."
+      },
+      {
+        guidance: "dont",
+        description: "Use it for a dashboard that scrolls. If the primary interaction is reading down a page, that's AppShell plus a Region, not a workspace."
+      }
+    ],
+    anatomy: [
+      {
+        name: "WorkspaceBar",
+        required: false,
+        description: "Top chrome at --chrome-bar-height with a hairline beneath: toolbar, document tabs, menubar row."
+      },
+      {
+        name: "Body",
+        required: true,
+        description: "The flexible middle row, normally a PanelGroup. Constrained so its children can shrink and scroll."
+      },
+      {
+        name: "WorkspaceCanvas",
+        required: false,
+        description: "The work surface and the main#main-content landmark the skip link targets. Clips rather than scrolls."
+      },
+      {
+        name: "StatusBar",
+        required: false,
+        description: "Bottom chrome for ambient document facts."
+      }
+    ]
+  },
+  related: {
+    components: ["PanelGroup", "PanelSection", "StatusBar", "ScrubField", "AppShell"]
+  },
+  status: "stable",
+  props: [
+    {
+      name: "toolbar",
+      type: "ReactNode",
+      description: "Top chrome, normally a WorkspaceBar."
+    },
+    { name: "statusBar", type: "ReactNode", description: "Bottom chrome, normally a StatusBar." },
+    {
+      name: "density",
+      type: '"compact" | "comfortable"',
+      default: '"compact"',
+      description: 'Density scope for everything inside. Sets the --control-* ladder via data-density; compact is the workspace register. Nothing hardcodes a height, so the same size="md" Button is 40px on a page and 32px inside a compact Workspace. A Dialog opened from inside resets to comfortable, because a modal is a page-register surface even when a tool launched it.'
+    },
+    {
+      name: "skipLinkLabel",
+      type: "string",
+      default: '"Skip to canvas"',
+      description: "Text for the skip link that targets the canvas landmark."
+    }
+  ],
+  subcomponents: [
+    {
+      name: "WorkspaceBar",
+      type: "ComponentProps<'header'>",
+      description: "The top chrome strip, sized to --chrome-bar-height with a hairline beneath."
+    },
+    {
+      name: "WorkspaceCanvas",
+      type: "ComponentProps<'main'>",
+      description: "The work surface: renders main#main-content, fills the body, clips its overflow."
+    }
+  ],
+  a11y: [
+    "Renders a skip link to #main-content as the first focusable element, even though there is no scrolling document.",
+    'WorkspaceCanvas is the <main id="main-content"> landmark; Panels are <aside> chrome with their own names.',
+    "Density only changes control sizes, never hit-target rules \u2014 an icon button at the 24px floor still needs a padded 44px hit area."
+  ],
+  tokensUsed: ["canvas", "canvas-foreground", "panel", "hairline", "popover", "popover-foreground", "ring"],
+  examples: [
+    {
+      label: "Editor shell",
+      code: `<Workspace
+  toolbar={
+    <WorkspaceBar>
+      <span className="px-1 text-ui-md text-foreground">Studio</span>
+      <Separator orientation="vertical" className="mx-1 h-4" />
+      <Button size="xs" variant="ghost">Open</Button>
+    </WorkspaceBar>
+  }
+  statusBar={
+    <StatusBar>
+      <span className="text-ui-num">1024 \xD7 768</span>
+      <StatusBarSeparator />
+      <span>3 layers</span>
+      <StatusBarGroup align="end"><span>Saved</span></StatusBarGroup>
+    </StatusBar>
+  }
+>
+  <PanelGroup>
+    <Panel label="Layers" width={240}>
+      <PanelSection title="Layers">
+        <PropertyRow label="Background"><Switch defaultChecked /></PropertyRow>
+      </PanelSection>
+    </Panel>
+    <WorkspaceCanvas>
+      <div className="grid h-full place-items-center text-ui-body text-muted-foreground">Canvas</div>
+    </WorkspaceCanvas>
+    <Panel label="Properties" width={256}>
+      <PanelSection title="Blending">
+        <PropertyPair>
+          <ScrubField label="Opacity" icon="grid" suffix="%" value={100} min={0} max={100} />
+          <ScrubField label="Blur" value={0} min={0} max={64} suffix="px" />
+        </PropertyPair>
+      </PanelSection>
+    </Panel>
+  </PanelGroup>
+</Workspace>`
+    },
+    {
+      label: "Console shell (no canvas)",
+      code: `<Workspace statusBar={<StatusBar><span>Connected</span></StatusBar>}>
+  <PanelGroup>
+    <Panel label="Sources" width={240}>
+      <PanelSection title="Sources">
+        <PropertyRow label="Filter"><Input placeholder="Search" /></PropertyRow>
+      </PanelSection>
+    </Panel>
+    <WorkspaceCanvas className="overflow-y-auto scrollbar-quiet">
+      <div className="p-3 text-ui-num text-muted-foreground">log output\u2026</div>
+    </WorkspaceCanvas>
+  </PanelGroup>
+</Workspace>`
+    },
+    {
+      label: "Comfortable density",
+      code: `<Workspace density="comfortable" toolbar={<WorkspaceBar><span className="text-ui-md">Review</span></WorkspaceBar>}>
+  <PanelGroup>
+    <WorkspaceCanvas>
+      <div className="grid h-full place-items-center text-body-md text-muted-foreground">Touch-friendly review mode</div>
+    </WorkspaceCanvas>
+  </PanelGroup>
+</Workspace>`
+    }
+  ]
+};
+export {
+  workspaceMeta
+};

package/dist/foundations/accessibility.js

@@ -0,0 +1,107 @@
+// src/foundations/accessibility.ts
+var accessibility = {
+  slug: "accessibility",
+  title: "Accessibility",
+  summary: "Sable's components ship accessible behavior from Base UI. These rules cover what an app composing them still has to get right.",
+  headline: "WCAG AA \xB7 44px targets \xB7 visible focus \xB7 reduced motion \xB7 logical properties",
+  vocabularies: [
+    {
+      title: "Floors",
+      terms: [
+        { name: "Contrast", value: "4.5:1 text \xB7 3:1 UI and large text", use: "Every semantic text/surface pair is checked per theme by contrast.test.ts." },
+        { name: "Hit area", value: "44\xD744px", use: "hit-target keeps a small control at the floor without moving layout." },
+        { name: "Focus", value: "ring-2 ring-ring, full opacity", use: "Visible on every interactive element, in light, dark and forced-colors." },
+        { name: "Mobile input text", value: "\u2265 16px", use: "iOS Safari zooms the page on focus below it." },
+        { name: "Reduced motion", value: "--motion-scale: 0", use: "Transitions resolve instantly; loaders hold their first frame." }
+      ]
+    }
+  ],
+  rules: [
+    {
+      rule: "Use the component, not a div with a click handler.",
+      why: "Base UI supplies roles, keyboard handling and focus management. A clickable div has none of them."
+    },
+    {
+      rule: "Every control has an accessible name.",
+      why: "Icon-only buttons take aria-label. Fields take a <Label> through <Field>, which also wires aria-describedby and aria-invalid."
+    },
+    {
+      rule: "A live region exists before it has anything to say.",
+      why: 'Render role="status" empty from the start and swap its text. A region inserted together with its content is announced inconsistently.'
+    },
+    {
+      rule: "On client-side navigation, update document.title and move focus to the new view's h1.",
+      why: "Route changes are silent to assistive technology unless the app announces them. AppShell supplies the skip link and landmarks; the app does the rest."
+    },
+    {
+      rule: "Keep submit enabled; validate on submit and focus the first invalid field.",
+      why: "A disabled submit hides why it is disabled. Focus is the only way a screen-reader user finds the error."
+    },
+    {
+      rule: "Use logical properties: ms-/me-/ps-/pe-/text-start/inset-inline-*.",
+      why: 'Flex and grid mirror for free under dir="rtl"; hand-positioned elements do not.',
+      enforcedBy: "design-lint: physical-direction (ratchet)"
+    },
+    {
+      rule: "Decorative layers over content take pointer-events-none and aria-hidden.",
+      why: "Scrims, glows and fades otherwise swallow clicks on the controls beneath."
+    },
+    {
+      rule: "Check focus and disabled states under forced-colors: active.",
+      why: "Windows High Contrast overrides ring colors and erases opacity-based disabled styling."
+    }
+  ],
+  noGos: [
+    {
+      never: "Color as the only signal (a red border with no message).",
+      instead: "Color plus text or an icon.",
+      why: "Roughly 1 in 12 men cannot tell red from green."
+    },
+    {
+      never: "Opacity on the focus ring.",
+      instead: "ring-ring at full opacity; tune the token in the theme.",
+      why: "A faded ring loses the contrast the theme tested.",
+      enforcedBy: "sable-lint: faded-focus-ring"
+    },
+    {
+      never: "A brand or status fill retuned under its old label \u2014 dark ink on a bright red that passes 4.5:1 at APCA Lc 42.",
+      instead: "A label that clears 4.5:1 and APCA Lc 60 in both modes. Move the fill's lightness, not its hue, keeping the ink its colour takes. A status colour on a surface is its own token (`--destructive-text`), so the fill can move freely.",
+      why: "The ratio alone passes labels that read muddy. A deliberate brand pair is allowed with a recorded reason (lint disable or preset exceptions).",
+      enforcedBy: "sable-lint: label-contrast"
+    },
+    {
+      never: 'Blocking paste, or type="number" for codes and card numbers.',
+      instead: 'type="text" inputMode="numeric" with the right autocomplete.',
+      why: "Blocking paste breaks password managers; number inputs scroll-change identifiers."
+    },
+    {
+      never: "forced-color-adjust: none to 'fix' high-contrast mode.",
+      instead: "Let the system colors apply; verify the result.",
+      why: "It removes the user's chosen colors exactly where they need them."
+    },
+    {
+      never: "outline: none without a replacement.",
+      instead: "focus-visible:ring-2 ring-ring.",
+      why: "Keyboard users lose their place."
+    }
+  ],
+  details: [
+    {
+      title: "An icon-only button",
+      before: '<Button size="icon"><Icon name="xmark" /></Button>',
+      after: '<Button size="icon" aria-label="Close"><Icon name="xmark" /></Button>',
+      why: "Without a name, a screen reader announces only 'button'."
+    },
+    {
+      title: "A status that announces",
+      before: '{saved && <p role="status">Saved</p>}',
+      after: '<p role="status">{saved ? "Saved" : ""}</p>',
+      why: "The region is in the accessibility tree before its text changes, so the change is announced."
+    }
+  ],
+  related: ["typography", "motion", "sable component <Name> --a11y"]
+};
+var accessibility_default = accessibility;
+export {
+  accessibility_default as default
+};