@sableui/react 0.6.2 → 0.7.1

package/dist/components/tree/tree.meta.js

@@ -0,0 +1,334 @@
+// src/components/tree/tree.meta.ts
+var treeMeta = {
+  name: "Tree",
+  summary: "The object list a tool is built around \u2014 layers, scene graph, outline \u2014 on one shared grid, so every left edge in the panel resolves to the rail or an exact multiple of the indent step.",
+  keywords: [
+    "tree",
+    "layers",
+    "outline",
+    "scene graph",
+    "hierarchy",
+    "nesting",
+    "indent",
+    "disclosure",
+    "workspace",
+    "panel",
+    "file tree",
+    "files",
+    "folders",
+    "explorer",
+    "treeview"
+  ],
+  usage: {
+    description: 'Use Tree for the hierarchy panel in a workspace: layers, objects, an inspector outline. It owns the geometry that makes nesting legible \u2014 the rail, the disclosure and type columns, and the indent step \u2014 via the density ladder (scope the panel with data-density, e.g. data-density="compact"), so nothing in the panel computes its own inset. It is also the file tree: nest rows with `subtree`, let folders manage their own open state with `defaultExpanded`, and mark kind with the `icon` convention (folder for a row with a subtree, file for a leaf). Reach for Accordion when the content is prose sections rather than nodes in a hierarchy.',
+    bestPractices: [
+      {
+        guidance: "do",
+        description: 'Give Tree an aria-label naming the hierarchy ("Layers", "Files"). It is a role="tree", and an unnamed tree is announced as just "tree".'
+      },
+      {
+        guidance: "do",
+        description: 'For a file tree, nest with `subtree` and use the icon convention: `icon={<Icon name="folder" />}` on a row with a subtree, `icon={<Icon name="file" />}` on a leaf. There are no folder/file presets \u2014 they would only bind those two props.'
+      },
+      {
+        guidance: "do",
+        description: "Give TreeAddRow the same depth as the rows it adds to, so its mark lands in their type column: one deeper than the parent for a child list, the parent's own depth for a sibling list."
+      },
+      {
+        guidance: "do",
+        description: "Put mutable per-row state (visibility, solo, a row menu) in `actions`, on the right rail. Show it on hover with `reveal-on-hover` (the row is its `group`), and at rest only when its value is the non-default one."
+      },
+      {
+        guidance: "do",
+        description: "Let section headers sit on the rail at the same height as a depth-0 row. Space and a hairline separate sections; TreeSection handles both, including dropping the divider on the first."
+      },
+      {
+        guidance: "dont",
+        description: "Hardcode a left inset anywhere in the panel. Use treeIndent(depth) or var(--tree-rail); a hand-written px value is how a tree ends up with four different left edges."
+      },
+      {
+        guidance: "dont",
+        description: "Redefine --tree-indent to anything other than --tree-column. A step smaller than the column puts a child's content left of its parent's and the nesting reads inverted."
+      },
+      {
+        guidance: "dont",
+        description: "Put the visibility toggle before the name. A leading toggle makes each row's visual start depend on its depth, so no two rows share an edge."
+      },
+      {
+        guidance: "dont",
+        description: "Hand-copy icon paths into a tree row. Use Icon and the shared semantic set, or provide an app-specific icon through the supported slot."
+      },
+      {
+        guidance: "dont",
+        description: "Use EmptyState inside a panel. It is page-register furniture (px-6 py-12 around a size-12 disc) and in 240px it spends 24px of inset and ~96px of height on nothing. Use TreeEmpty."
+      },
+      {
+        guidance: "dont",
+        description: "Show explanatory prose AND an add row in an empty section. That is two things to read where one carries the affordance; give TreeEmpty a one-line message and pass the add row as its action."
+      },
+      {
+        guidance: "dont",
+        description: "Leave a section actionable when its action cannot do anything yet \u2014 a document-level effect list with no content to apply to, for instance. Hide the section or its affordance until the thing it operates on exists."
+      }
+    ],
+    anatomy: [
+      {
+        name: "Tree",
+        required: true,
+        description: "The container. Does not scroll itself \u2014 put it in a scrolling Panel, or make it the scrolling region with className."
+      },
+      {
+        name: "TreeSection",
+        required: false,
+        description: "A titled group. Header on the rail, hairline above, divider suppressed on the first section."
+      },
+      {
+        name: "TreeRow",
+        required: true,
+        description: "One node: rail, disclosure column, type column, name, right-rail actions."
+      },
+      {
+        name: "TreeAddRow",
+        required: false,
+        description: "The affordance that ends a branch. Mark in the type column, label in the name column."
+      },
+      {
+        name: "TreeEmpty",
+        required: false,
+        description: "A section's empty state at panel scale: one line, one action, optionally a dashed drop region."
+      }
+    ]
+  },
+  related: {
+    components: ["Panel", "PanelSection", "Workspace", "Accordion", "SideNav"]
+  },
+  status: "stable",
+  props: [
+    {
+      name: "depth",
+      type: "number",
+      default: "0",
+      description: "Nesting level, on TreeRow and TreeAddRow. 0 sits on the rail; each level adds one --tree-indent."
+    },
+    {
+      name: "expandable",
+      type: "boolean",
+      default: "true with subtree, else false",
+      description: "Whether TreeRow renders a disclosure control. The column is reserved either way, so leaf and parent names stay aligned."
+    },
+    {
+      name: "expanded",
+      type: "boolean",
+      description: "Controlled open state for a TreeRow. Pair with onExpandedChange; omit both for an uncontrolled row."
+    },
+    {
+      name: "defaultExpanded",
+      type: "boolean",
+      default: "true",
+      description: "Uncontrolled initial open state, used when `expanded` is not passed. Pass false for a file tree's closed folders."
+    },
+    {
+      name: "onExpandedChange",
+      type: "(expanded: boolean) => void",
+      description: "Called when a TreeRow opens or closes \u2014 from the disclosure, ArrowRight/ArrowLeft, or activating a row that has no onClick. Fires in both controlled and uncontrolled use."
+    },
+    {
+      name: "subtree",
+      type: "ReactNode",
+      description: "The rows nested under a TreeRow, rendered after it while it is expanded. Nested rows inherit depth + 1 unless they pass their own `depth`, so a file tree never computes depth by hand."
+    },
+    {
+      name: "selected",
+      type: "boolean",
+      default: "false",
+      description: "Selection fill and accent bar on a TreeRow. Inside a Tree it is exposed as aria-selected on the treeitem; a row rendered outside a Tree is a plain div and exposes aria-current instead."
+    },
+    {
+      name: "toggleLabel",
+      type: "string",
+      description: `Names the thing being disclosed, for the toggle's accessible label \u2014 "Expand Background" rather than "Expand group". Every example passes it; a screen-reader user hearing twenty identical "Expand group" buttons has no way to tell them apart.`
+    },
+    {
+      name: "icon",
+      type: "ReactNode",
+      description: "The kind marker for a TreeRow, rendered in the type column at 1em. Use a semantic Icon so it follows the app icon set."
+    },
+    {
+      name: "disclosureIcon",
+      type: "ReactNode",
+      description: "Replaces TreeRow's semantic chevron-down icon. Omit to use the chevron-down from the app's IconProvider set."
+    },
+    {
+      name: "actions",
+      type: "ReactNode",
+      description: "Right-rail controls for a TreeRow: visibility, solo, a row menu."
+    },
+    {
+      name: "label",
+      type: "ReactNode",
+      description: "TreeAddRow's visible label. Name what gets added \u2014 'Add effect', not 'Add'."
+    }
+  ],
+  subcomponents: [
+    {
+      name: "TreeSection",
+      type: "{ title: ReactNode; hint?: string; action?: ReactNode }",
+      description: "A titled group of rows, with the header on the rail."
+    },
+    {
+      name: "TreeRow",
+      type: "{ depth?: number; selected?: boolean; accent?: boolean; dimmed?: boolean; expandable?: boolean; expanded?: boolean; defaultExpanded?: boolean; onExpandedChange?: (expanded: boolean) => void; subtree?: ReactNode; toggleLabel?: string; disclosureIcon?: ReactNode; icon?: ReactNode; actions?: ReactNode }",
+      description: "One node in the hierarchy (role=treeitem inside a Tree). Controlled via expanded/onExpandedChange or uncontrolled via defaultExpanded; nest children with subtree. Always reserves both leading columns (disclosure and type), so a leaf's name lines up with its expandable siblings."
+    },
+    {
+      name: "TreeAddRow",
+      type: "{ depth?: number; label: ReactNode; icon?: ReactNode }",
+      description: "The add affordance, shaped as a row and aligned to the branch it adds to. Its mark sits in the type column (level with the siblings' kind markers), not the name column. `icon` replaces the built-in add mark."
+    },
+    {
+      name: "TreeEmpty",
+      type: "{ message: ReactNode; action?: ReactNode; dropTarget?: boolean; depth?: number }",
+      description: "A section's or a branch's empty state, at panel scale rather than page scale. One-line message, one action slot; dropTarget renders it as a dashed drop region and sets data-drop-target for styling. `depth` (inherited inside a subtree) starts the line on the edge of the rows that branch would hold."
+    },
+    {
+      name: "treeIndent",
+      type: "(depth: number) => string",
+      description: "The left inset for a depth, as a calc() expression reading the density ladder. Use this rather than computing pixels."
+    }
+  ],
+  a11y: [
+    `Tree implements the ARIA tree view pattern: Tree is role="tree", each TreeRow and TreeAddRow is role="treeitem" with aria-level, expandable rows carry aria-expanded, and a TreeSection is a role="group" labelled by its heading. Rows stay flat in the DOM \u2014 hierarchy is aria-level \u2014 so the fills span the panel's full width.`,
+    "Keyboard: exactly one row is in the tab order (roving tabindex, seeded on the selected row, else the first). ArrowUp/Down move between visible rows; ArrowRight expands a collapsed row, then steps to its first child; ArrowLeft collapses an expanded row, else steps to its parent; Home/End jump to the ends; Enter/Space activate the row \u2014 its onClick, or toggling it when it has none. Keys pressed inside a row's own controls (an action button, a rename field) are left to that control.",
+    'Selection has one mapping: inside a Tree, `selected` is aria-selected on the treeitem; outside a Tree the row is a plain div, where aria-selected is invalid, so it falls back to aria-current. A navigation tree that wants aria-current="page" passes it through props.',
+    "Each treeitem is named by its own label (aria-labelledby the name), never by the text of its icon or action buttons.",
+    "The disclosure is a real button with aria-expanded and a label naming what it discloses, and it stops propagation so collapsing a group never changes the selection. Inside a Tree the treeitem carries aria-expanded and the arrow keys, so the button becomes a pointer target only: aria-hidden, out of the tab order, and it leaves focus where it was when clicked.",
+    "The disclosure's POINTER TARGET is bigger than the mark it draws. `--tree-column` is 20px comfortable and 18px compact, both under WCAG 2.5.8's 24x24 floor, so a centred pseudo-element takes the hit at `--control-xs` (28/24) instead. The drawn box stays on the column, because that column is also the indent step \u2014 growing the button would push every name in the tree one column right.",
+    "Right-rail actions stay in the tab order, so a row with actions costs extra Tab stops. Keep actions few and reveal them with `reveal-on-hover`, which also shows them on focus and always on touch.",
+    "`dimmed` is presentation only. A row switched off must also say so in its actions' aria-pressed or its accessible name; opacity alone is invisible to a screen reader and fails contrast.",
+    "Right-rail controls that appear on hover must also appear on focus-visible, or they are unreachable by keyboard."
+  ],
+  tokensUsed: ["panel-raised", "hairline", "foreground", "muted-foreground", "primary", "ring"],
+  examples: [
+    {
+      label: "File tree",
+      code: `// Nest with subtree; folders own their open state via defaultExpanded.
+// A row with no onClick toggles when clicked or activated, like a folder in
+// a file explorer. Depth is inherited \u2014 never computed by hand.
+<Tree aria-label="Files" className="max-w-xs">
+  <TreeRow
+    icon={<Icon name="folder" />}
+    toggleLabel="src"
+    subtree={
+      <>
+        <TreeRow icon={<Icon name="file" />} onClick={() => open("index.ts")}>index.ts</TreeRow>
+        <TreeRow
+          icon={<Icon name="folder" />}
+          toggleLabel="components"
+          defaultExpanded={false}
+          subtree={
+            <TreeRow icon={<Icon name="file" />} selected onClick={() => open("button.tsx")}>
+              button.tsx
+            </TreeRow>
+          }
+        >
+          components
+        </TreeRow>
+      </>
+    }
+  >
+    src
+  </TreeRow>
+  <TreeRow icon={<Icon name="file" />} onClick={() => open("README.md")}>README.md</TreeRow>
+</Tree>`
+    },
+    {
+      label: "Layer tree with per-node effects",
+      code: `<Tree aria-label="Layers" className="min-h-0 flex-1 overflow-y-auto scrollbar-quiet">
+  <TreeSection title="Document effects" hint="Applied to the flattened composite">
+    <TreeRow depth={0} icon={<Icon name="sparkles" />}>Channel shift</TreeRow>
+    <TreeAddRow depth={0} label="Add effect" />
+  </TreeSection>
+
+  <TreeSection title="Layers" action={<span className="text-ui-num text-muted-foreground">2</span>}>
+    <TreeRow
+      depth={0}
+      expandable
+      expanded
+      toggleLabel="Backdrop"
+      icon={<Icon name="image-stack" />}
+      actions={<Button size="icon-xs" variant="ghost" aria-label="Hide Backdrop"><Icon name="eye" /></Button>}
+    >
+      Backdrop
+    </TreeRow>
+    <TreeRow depth={1} icon={<Icon name="sparkles" />}>Block displacement</TreeRow>
+    <TreeAddRow depth={1} label="Add effect" />
+
+    <TreeRow depth={0} icon={<Icon name="image-stack" />} dimmed>Overlay</TreeRow>
+    <TreeAddRow depth={0} label="Add image" />
+  </TreeSection>
+</Tree>`
+    },
+    {
+      label: "Empty state \u2014 one line, one action",
+      code: `// A section with nothing in it offers exactly ONE way forward. Not EmptyState:
+// that is page-register (px-6 py-12 around a size-12 disc) and in a 240px panel
+// it spends 24px of inset and ~96px of height on nothing.
+<TreeSection title="Layers">
+  <TreeEmpty message="No images yet" action={<TreeAddRow depth={0} label="Add image" />} />
+</TreeSection>
+
+// As a drop region \u2014 the app owns the drag handlers; TreeEmpty owns the frame
+// and sets data-drop-target so a data-[drop-active] style can respond.
+<TreeEmpty
+  dropTarget
+  message="Drop an image"
+  data-drop-active={dragging || undefined}
+  onDragOver={(e) => { e.preventDefault(); setDragging(true) }}
+  onDragLeave={() => setDragging(false)}
+  onDrop={handleDrop}
+  className="data-[drop-active]:border-primary"
+/>`
+    },
+    {
+      label: "Selection and disclosure",
+      code: `<Tree aria-label="Layers">
+  <TreeRow
+    depth={0}
+    expandable
+    expanded={open}
+    onExpandedChange={setOpen}
+    toggleLabel="Group 1"
+    icon={<Icon name="folder" />}
+    selected
+    onClick={() => select("group-1")}
+  >
+    Group 1
+  </TreeRow>
+  {open ? <TreeRow depth={1} icon={<Icon name="file" />}>Child</TreeRow> : null}
+</Tree>`
+    },
+    {
+      label: "An empty branch",
+      code: `// A layer with no effects: TreeEmpty at the branch's depth lands on the
+// same edge its effect rows would \u2014 no hand-computed inset.
+<TreeRow depth={0} icon={<Icon name="image-stack" />} toggleLabel="Overlay" subtree={
+  <>
+    <TreeEmpty message="No effects yet" />
+    <TreeAddRow label="Add effect" />
+  </>
+}>
+  Overlay
+</TreeRow>`
+    },
+    {
+      label: "Aligning a custom affordance",
+      code: `// Anything else that needs a tree inset reads it from the same place the rows do.
+<div style={{ paddingInlineStart: treeIndent(1) }} className="flex h-(--control-xs) items-center">
+  <span className="text-ui-body text-muted-foreground">Drag a layer here</span>
+</div>`
+    }
+  ]
+};
+export {
+  treeMeta
+};

package/dist/components/video/index.js

@@ -0,0 +1,7 @@
+// src/components/video/index.ts
+import { Video } from "./video.js";
+import { videoMeta } from "./video.meta.js";
+export {
+  Video,
+  videoMeta
+};

package/dist/components/video/video.js

@@ -0,0 +1,59 @@
+// src/components/video/video.tsx
+import { Icon } from "../../icon/index.js";
+import { cn } from "../../lib/cn.js";
+import { jsx, jsxs } from "react/jsx-runtime";
+var PLAY_MARK = "flex size-14 items-center justify-center rounded-full bg-overlay/85 text-overlay-foreground shadow-sm";
+function Video({
+  src,
+  poster,
+  controls = true,
+  onRequestPlay,
+  className,
+  ...props
+}) {
+  return /* @__PURE__ */ jsx(
+    "div",
+    {
+      className: cn(
+        "relative aspect-video overflow-hidden rounded-lg border border-border bg-overlay",
+        className
+      ),
+      children: src ? /* @__PURE__ */ jsx(
+        "video",
+        {
+          className: "size-full",
+          controls,
+          poster,
+          src,
+          ...props
+        }
+      ) : /* @__PURE__ */ jsxs("div", { className: "size-full", children: [
+        poster ? /* @__PURE__ */ jsx(
+          "img",
+          {
+            src: poster,
+            alt: "",
+            className: "size-full object-cover"
+          }
+        ) : null,
+        /* @__PURE__ */ jsx("div", { className: "absolute inset-0 flex items-center justify-center", children: onRequestPlay ? (
+          // design-lint-disable-next-line raw-button -- an on-media play disc: it needs the overlay token pair and a 56px circle, and no Button variant or size offers either (Button has no overlay variant yet)
+          /* @__PURE__ */ jsx(
+            "button",
+            {
+              type: "button",
+              "aria-label": "Play video",
+              onClick: onRequestPlay,
+              className: cn(PLAY_MARK, "cursor-pointer motion-interactive motion-press hover:bg-overlay focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"),
+              children: /* @__PURE__ */ jsx(Icon, { name: "play", variant: "solid", className: "translate-x-px text-xl" })
+            }
+          )
+        ) : /* @__PURE__ */ jsx("div", { "aria-hidden": true, className: PLAY_MARK, children: /* @__PURE__ */ jsx(Icon, { name: "play", variant: "solid", className: "translate-x-px text-xl" }) }) })
+      ] })
+    }
+  );
+}
+Video.displayName = "Video";
+export {
+  Video
+};

package/dist/components/video/video.meta.js

@@ -0,0 +1,81 @@
+// src/components/video/video.meta.ts
+var videoMeta = {
+  name: "Video",
+  summary: "Styled 16:9 video player frame. Mounts a native <video> when given a src, or shows a poster/placeholder with a centered play overlay.",
+  status: "stable",
+  keywords: [
+    "video",
+    "media",
+    "player",
+    "demo"
+  ],
+  usage: {
+    description: "Use Video to embed playable or previewable video media inside a page.",
+    bestPractices: [
+      {
+        guidance: "do",
+        description: "Use captions, poster imagery, and controls when the video carries information."
+      },
+      {
+        guidance: "do",
+        description: "Keep the surrounding layout stable while media loads."
+      },
+      {
+        guidance: "dont",
+        description: "Do not autoplay important audio or make video the only way to access required information."
+      },
+      {
+        guidance: "dont",
+        description: "Do not ship it without captions or a transcript. Captions are what make video usable for deaf users and searchable for everyone; a video with neither is inaccessible content you also cannot index."
+      }
+    ]
+  },
+  related: {
+    components: ["Carousel", "Dialog", "Badge"]
+  },
+  props: [
+    {
+      name: "onRequestPlay",
+      type: "() => void",
+      description: 'Placeholder only (no src): renders the play mark as a real button labelled "Play video" that calls this \u2014 e.g. to load the source. Without it the mark is decorative.'
+    },
+    {
+      name: "src",
+      type: "string",
+      description: "Video source URL. When omitted, a poster/placeholder with a play overlay renders."
+    },
+    {
+      name: "poster",
+      type: "string",
+      description: "Poster image shown before playback (and as the placeholder backdrop)."
+    },
+    {
+      name: "controls",
+      type: "boolean",
+      default: "true",
+      description: "Show native playback controls."
+    }
+  ],
+  tokensUsed: ["border", "overlay", "overlay-foreground", "ring"],
+  a11y: [
+    "Mounts a native <video> element, preserving built-in keyboard controls when controls is enabled.",
+    'Without onRequestPlay the placeholder play mark is decorative (aria-hidden) \u2014 nothing on the frame pretends to be pressable. With it, the mark is a native button named "Play video".'
+  ],
+  examples: [
+    {
+      label: "With a poster",
+      code: '<Video poster="/cover.jpg" src="/clip.mp4" />'
+    },
+    {
+      label: "Placeholder (no src)",
+      code: '<Video poster="/cover.jpg" />'
+    },
+    {
+      label: "Placeholder that loads on play",
+      code: '<Video poster="/cover.jpg" src={src} onRequestPlay={() => setSrc("/clip.mp4")} />'
+    }
+  ]
+};
+export {
+  videoMeta
+};

package/dist/components/workspace/index.js

@@ -0,0 +1,9 @@
+// src/components/workspace/index.ts
+import { Workspace, WorkspaceBar, WorkspaceCanvas } from "./workspace.js";
+import { workspaceMeta } from "./workspace.meta.js";
+export {
+  Workspace,
+  WorkspaceBar,
+  WorkspaceCanvas,
+  workspaceMeta
+};

package/dist/components/workspace/workspace.js

@@ -0,0 +1,79 @@
+"use client";
+
+// src/components/workspace/workspace.tsx
+import { cn } from "../../lib/cn.js";
+import { DensityProvider } from "../../lib/density.js";
+import { jsx, jsxs } from "react/jsx-runtime";
+function Workspace({
+  toolbar,
+  statusBar,
+  density = "compact",
+  skipLinkLabel = "Skip to canvas",
+  className,
+  children,
+  ...props
+}) {
+  return (
+    // `data-density` scopes the ladder via CSS for everything in the subtree;
+    // DensityProvider carries the same value to anything that PORTALS out of it.
+    // A menu or select popup mounts at the document root, so CSS reaches it
+    // never — measured, its --control-md resolved to the comfortable 40px while
+    // the workspace around it was 32px, and --button-radius reverted to pills.
+    /* @__PURE__ */ jsx(DensityProvider, { value: density, children: /* @__PURE__ */ jsxs(
+      "div",
+      {
+        "data-density": density,
+        className: cn(
+          "grid h-dvh grid-rows-[auto_minmax(0,1fr)_auto] overflow-hidden bg-canvas text-canvas-foreground",
+          className
+        ),
+        ...props,
+        children: [
+          /* @__PURE__ */ jsx(
+            "a",
+            {
+              href: "#main-content",
+              className: "sr-only focus:not-sr-only focus:absolute focus:start-2 focus:top-2 focus:z-(--z-skip-link) focus:rounded-sm focus:bg-popover focus:px-3 focus:py-2 focus:text-ui-md focus:text-popover-foreground focus:ring-2 focus:ring-ring",
+              children: skipLinkLabel
+            }
+          ),
+          toolbar,
+          /* @__PURE__ */ jsx("div", { className: "grid min-h-0 grid-cols-1", children }),
+          statusBar
+        ]
+      }
+    ) })
+  );
+}
+Workspace.displayName = "Workspace";
+function WorkspaceCanvas({ className, children, ...props }) {
+  return /* @__PURE__ */ jsx(
+    "main",
+    {
+      id: "main-content",
+      className: cn("relative min-h-0 min-w-0 flex-1 overflow-hidden bg-canvas", className),
+      ...props,
+      children
+    }
+  );
+}
+WorkspaceCanvas.displayName = "WorkspaceCanvas";
+function WorkspaceBar({ className, children, ...props }) {
+  return /* @__PURE__ */ jsx(
+    "header",
+    {
+      className: cn(
+        "flex h-(--chrome-bar-height) shrink-0 items-center gap-1 border-b border-hairline bg-panel px-2",
+        className
+      ),
+      ...props,
+      children
+    }
+  );
+}
+WorkspaceBar.displayName = "WorkspaceBar";
+export {
+  Workspace,
+  WorkspaceBar,
+  WorkspaceCanvas
+};