@sableui/react 0.6.1 → 0.7.0

package/dist/components/tooltip/tooltip.meta.js

@@ -0,0 +1,156 @@
+// src/components/tooltip/tooltip.meta.ts
+var tooltipMeta = {
+  name: "Tooltip",
+  summary: "Hover/focus label over Base UI Tooltip (collision-aware positioning, ARIA wiring, delay grouping via TooltipProvider). Compact popover surface.",
+  status: "stable",
+  keywords: [
+    "tooltip",
+    "hint",
+    "hover",
+    "assistive"
+  ],
+  usage: {
+    description: "Use Tooltip for brief nonessential hints tied to a specific control or piece of text.",
+    bestPractices: [
+      {
+        guidance: "do",
+        description: "Use it to name icon-only controls or clarify compact UI when the label cannot be visible."
+      },
+      {
+        guidance: "do",
+        description: "Keep tooltip content short and noninteractive."
+      },
+      {
+        guidance: "dont",
+        description: "Do not put critical instructions, errors, or interactive content inside Tooltip."
+      },
+      {
+        guidance: "dont",
+        description: `Do not let a tooltip serve as an icon button's accessible name. A tooltip is not a name \u2014 without its own aria-label the button announces as "button", and the tooltip never opens for a screen reader at all.`
+      }
+    ],
+    anatomy: [
+      {
+        name: "TooltipProvider",
+        required: false,
+        description: "Optional provider for shared tooltip timing."
+      },
+      {
+        name: "TooltipTrigger",
+        required: true,
+        description: "The element that owns the hint."
+      },
+      {
+        name: "TooltipContent",
+        required: true,
+        description: "The short hint content."
+      },
+      {
+        name: "TooltipArrow",
+        required: false,
+        description: "An optional pointer toward the trigger."
+      },
+      {
+        name: "SimpleTooltip",
+        required: false,
+        description: "A convenience wrapper for common tooltip usage."
+      }
+    ]
+  },
+  related: {
+    components: [
+      "Popover",
+      "ContextCard"
+    ]
+  },
+  props: [
+    {
+      name: "side",
+      type: '"top" | "right" | "bottom" | "left"',
+      default: '"top"',
+      description: "On TooltipContent: which side of the trigger to render against. Flips automatically when there is no room."
+    },
+    {
+      name: "Tooltip (Root)",
+      type: "Base UI Tooltip.Root props (open, defaultOpen, onOpenChange, disabled)",
+      description: "Groups the trigger and content. Uncontrolled by default."
+    }
+  ],
+  subcomponents: [
+    {
+      name: "TooltipProvider",
+      type: "Base UI Tooltip.Provider props (delay, closeDelay, timeout)",
+      description: "Wraps an app or group of Tooltips to share open/close delays. Once one tooltip is open, adjacent tooltips open instantly."
+    },
+    {
+      name: "TooltipTrigger",
+      type: "Base UI Trigger props + render",
+      description: "The anchor element. Use render={<Button/>} to compose with another component."
+    },
+    {
+      name: "TooltipContent",
+      type: "Base UI Popup props + side | align | sideOffset + className",
+      description: 'Portals + positions + paints the popup. side ("top" | "bottom" | "left" | "right" | "inline-*") picks which side of the trigger to render against, defaults to "top", and auto-flips on collision; align ("start" | "center" | "end") defaults to "center"; sideOffset (gap between trigger and popup, in pixels) defaults to 6.'
+    },
+    {
+      name: "TooltipArrow",
+      type: "Base UI Arrow props + className",
+      description: "Optional pointer connecting the popup to its trigger \u2014 a popover-coloured square turned 45\xB0 that carries the border on its outward edges. Place inside TooltipContent."
+    },
+    {
+      name: "SimpleTooltip",
+      type: "Base UI Tooltip.Root props + content: ReactNode + children: ReactElement + side | align | sideOffset",
+      description: "Shorthand wrapping Root + Trigger + Content for the common case. The single child becomes the trigger (via Base UI render); content sets the body; side / align / sideOffset forward to the content with the same defaults. Composition parts remain for advanced use."
+    }
+  ],
+  tokensUsed: ["popover", "popover-foreground", "border-floating"],
+  motion: [
+    {
+      slot: "arrival",
+      recipe: "motion-pop",
+      part: "Content",
+      why: "The transform-origin follows the anchor, so the tooltip appears to grow out of the element it describes. That is what binds it to its trigger \u2014 a bubble that materialises at full size near two possible triggers belongs to neither."
+    },
+    {
+      slot: "response",
+      recipe: "none",
+      part: "Content",
+      why: "The tooltip is not a hover target; pointing at it is how you dismiss it. Styling it for the pointer would suggest otherwise."
+    },
+    {
+      slot: "transition",
+      recipe: "motion-pop",
+      part: "Content",
+      why: "Same recipe, exit direction \u2014 it collapses back toward the anchor. Content that fades from a fixed size on close reads as a second, unrelated element disappearing."
+    },
+    {
+      slot: "activity",
+      recipe: "none",
+      part: "Content",
+      why: "Tooltip copy is resident before the tooltip opens. Anything that has to be fetched is a Popover with its own loading state."
+    }
+  ],
+  a11y: [
+    "Base UI wires aria-describedby from trigger to popup and manages hover + focus open.",
+    "Opens on keyboard focus, not just hover; dismisses on Esc and blur.",
+    "Animate via data-[starting-style]/data-[ending-style] opacity attributes.",
+    "Tooltip text is supplementary \u2014 never put essential-only actions inside a tooltip."
+  ],
+  examples: [
+    {
+      label: "Basic",
+      code: '<TooltipProvider><Tooltip><TooltipTrigger render={<Button variant="ghost" size="icon-sm" aria-label="Info"><Icon name="info" /></Button>} /><TooltipContent>Stored permanently on Arweave.</TooltipContent></Tooltip></TooltipProvider>'
+    },
+    {
+      label: "Sides",
+      code: '<Tooltip><TooltipTrigger render={<Button variant="secondary">Right</Button>} /><TooltipContent side="right">Opens to the right</TooltipContent></Tooltip>'
+    },
+    {
+      label: "Shorthand (SimpleTooltip)",
+      code: '<SimpleTooltip content="Stored permanently on Arweave."><Button variant="ghost" size="icon-sm" aria-label="Info"><Icon name="info" /></Button></SimpleTooltip>'
+    }
+  ]
+};
+export {
+  tooltipMeta
+};

package/dist/components/tree/index.js

@@ -0,0 +1,12 @@
+// src/components/tree/index.ts
+import { Tree, TreeAddRow, TreeEmpty, TreeRow, TreeSection, treeIndent } from "./tree.js";
+import { treeMeta } from "./tree.meta.js";
+export {
+  Tree,
+  TreeAddRow,
+  TreeEmpty,
+  TreeRow,
+  TreeSection,
+  treeIndent,
+  treeMeta
+};

package/dist/components/tree/tree.js

@@ -0,0 +1,364 @@
+"use client";
+
+// src/components/tree/tree.tsx
+import {
+  createContext,
+  useCallback,
+  useContext,
+  useEffect,
+  useId,
+  useLayoutEffect,
+  useMemo,
+  useRef,
+  useState
+} from "react";
+import { Icon } from "../../icon/index.js";
+import { cn } from "../../lib/cn.js";
+import { hitTargetMin } from "../../lib/hit-target.js";
+import { Fragment, jsx, jsxs } from "react/jsx-runtime";
+function treeIndent(depth) {
+  return `calc(var(--tree-rail) + var(--tree-indent) * ${Math.max(0, depth)})`;
+}
+function DisclosureMark() {
+  return /* @__PURE__ */ jsx(Icon, { name: "chevron-down" });
+}
+function AddMark() {
+  return /* @__PURE__ */ jsx(Icon, { name: "plus" });
+}
+var COLUMN_SLOT = "flex shrink-0 items-center justify-center [font-size:var(--tree-column)]";
+var COLUMN_BOX = { width: "var(--tree-column)", height: "var(--tree-column)" };
+var TreeContext = createContext(null);
+var TreeDepthContext = createContext(0);
+var ITEM = '[role="treeitem"]';
+function useTreeItem(idProp) {
+  const ctx = useContext(TreeContext);
+  const generated = useId();
+  const id = idProp ?? generated;
+  const release = ctx?.release;
+  useEffect(() => () => release?.(id), [release, id]);
+  return {
+    inTree: ctx !== null,
+    id,
+    tabIndex: ctx ? ctx.focusedId === id ? 0 : -1 : void 0,
+    claimFocus: () => ctx?.setFocusedId(id)
+  };
+}
+var ITEM_FOCUS = "focus-visible:outline-2 focus-visible:outline-offset-[-2px] focus-visible:outline-ring";
+function Tree({ className, children, onKeyDown, ...props }) {
+  const [focusedId, setFocusedId] = useState(null);
+  const rootRef = useRef(null);
+  const items = () => Array.from(rootRef.current?.querySelectorAll(ITEM) ?? []).filter(
+    (el) => el.closest('[role="tree"]') === rootRef.current
+  );
+  useLayoutEffect(() => {
+    const all = items();
+    if (all.length === 0) return;
+    if (focusedId && all.some((el) => el.id === focusedId)) return;
+    const next = all.find((el) => el.getAttribute("aria-selected") === "true") ?? all[0];
+    if (next && next.id !== focusedId) setFocusedId(next.id);
+  });
+  const release = useCallback(
+    (id) => setFocusedId((prev) => prev === id ? null : prev),
+    []
+  );
+  const context = useMemo(
+    () => ({ focusedId, setFocusedId, release }),
+    [focusedId, release]
+  );
+  const handleKeyDown = (event) => {
+    onKeyDown?.(event);
+    if (event.defaultPrevented) return;
+    const current = event.target;
+    if (current.getAttribute("role") !== "treeitem") return;
+    const all = items();
+    const index = all.indexOf(current);
+    if (index === -1) return;
+    const level = (el) => Number(el.getAttribute("aria-level") ?? 1);
+    const expanded = current.getAttribute("aria-expanded");
+    const toggle = () => current.querySelector("[data-tree-toggle]")?.click();
+    const move = (el) => {
+      event.preventDefault();
+      el?.focus();
+    };
+    switch (event.key) {
+      case "ArrowDown":
+        move(all[index + 1]);
+        break;
+      case "ArrowUp":
+        move(all[index - 1]);
+        break;
+      case "Home":
+        move(all[0]);
+        break;
+      case "End":
+        move(all[all.length - 1]);
+        break;
+      case "ArrowRight": {
+        if (expanded === "false") {
+          event.preventDefault();
+          toggle();
+        } else if (expanded === "true") {
+          const next = all[index + 1];
+          move(next && level(next) > level(current) ? next : void 0);
+        }
+        break;
+      }
+      case "ArrowLeft": {
+        if (expanded === "true") {
+          event.preventDefault();
+          toggle();
+        } else {
+          const own = level(current);
+          move(all.slice(0, index).reverse().find((el) => level(el) < own));
+        }
+        break;
+      }
+      case "Enter":
+      case " ":
+        event.preventDefault();
+        current.click();
+        break;
+    }
+  };
+  return /* @__PURE__ */ jsx(TreeContext.Provider, { value: context, children: /* @__PURE__ */ jsx(
+    "div",
+    {
+      ref: rootRef,
+      role: "tree",
+      onKeyDown: handleKeyDown,
+      className: cn("flex flex-col py-1", className),
+      ...props,
+      children
+    }
+  ) });
+}
+Tree.displayName = "Tree";
+function TreeSection({ title, hint, action, className, children, ...props }) {
+  const inTree = useContext(TreeContext) !== null;
+  const headingId = useId();
+  return /* @__PURE__ */ jsxs(
+    "section",
+    {
+      role: inTree ? "group" : void 0,
+      "aria-labelledby": inTree ? headingId : void 0,
+      className: cn(
+        "flex flex-col border-t border-hairline pt-1",
+        "mt-2 first:mt-0 first:border-t-0 first:pt-0",
+        className
+      ),
+      ...props,
+      children: [
+        /* @__PURE__ */ jsxs(
+          "header",
+          {
+            style: { paddingInlineStart: "var(--tree-rail)" },
+            className: "flex h-(--control-xs) shrink-0 items-center justify-between gap-2 pe-2",
+            children: [
+              /* @__PURE__ */ jsx("h3", { id: headingId, title: hint, className: "min-w-0 truncate text-ui-section text-muted-foreground", children: title }),
+              action
+            ]
+          }
+        ),
+        children
+      ]
+    }
+  );
+}
+TreeSection.displayName = "TreeSection";
+function TreeRow({
+  depth: depthProp,
+  selected = false,
+  accent = true,
+  dimmed = false,
+  expandable: expandableProp,
+  expanded: expandedProp,
+  defaultExpanded = true,
+  onExpandedChange,
+  subtree,
+  toggleLabel,
+  disclosureIcon,
+  icon,
+  actions,
+  className,
+  style,
+  id: idProp,
+  onClick,
+  onFocus,
+  children,
+  ...props
+}) {
+  const inheritedDepth = useContext(TreeDepthContext);
+  const depth = depthProp ?? inheritedDepth;
+  const expandable = expandableProp ?? subtree !== void 0;
+  const [innerExpanded, setInnerExpanded] = useState(defaultExpanded);
+  const controlled = expandedProp !== void 0;
+  const expanded = controlled ? expandedProp : innerExpanded;
+  const setExpanded = (next) => {
+    if (!controlled) setInnerExpanded(next);
+    onExpandedChange?.(next);
+  };
+  const item = useTreeItem(idProp);
+  const nameId = useId();
+  const row = /* @__PURE__ */ jsxs(
+    "div",
+    {
+      ...props,
+      id: item.inTree ? item.id : idProp,
+      "data-selected": selected || void 0,
+      role: item.inTree ? "treeitem" : void 0,
+      "aria-level": item.inTree ? depth + 1 : void 0,
+      "aria-expanded": item.inTree && expandable ? expanded : void 0,
+      "aria-selected": item.inTree ? selected : void 0,
+      "aria-current": !item.inTree && selected ? true : void 0,
+      "aria-labelledby": item.inTree ? nameId : void 0,
+      tabIndex: item.tabIndex,
+      onFocus: (event) => {
+        item.claimFocus();
+        onFocus?.(event);
+      },
+      onClick: onClick ?? (expandable ? () => setExpanded(!expanded) : void 0),
+      style: { paddingInlineStart: treeIndent(depth), ...style },
+      className: cn(
+        "group relative flex h-(--control-xs) items-center gap-1.5 rounded-xs pe-1 motion-interactive",
+        selected ? "bg-panel-raised" : "hover:bg-panel-raised/60",
+        item.inTree && ITEM_FOCUS,
+        dimmed && "opacity-50",
+        className
+      ),
+      children: [
+        selected && accent ? /* @__PURE__ */ jsx(
+          "span",
+          {
+            "aria-hidden": true,
+            className: "absolute inset-y-0.5 start-0 w-0.5 rounded-full bg-primary"
+          }
+        ) : null,
+        expandable ? /* @__PURE__ */ jsx(
+          "button",
+          {
+            type: "button",
+            "data-tree-toggle": "",
+            "aria-expanded": expanded,
+            "aria-label": expanded ? `Collapse ${toggleLabel ?? "group"}` : `Expand ${toggleLabel ?? "group"}`,
+            "aria-hidden": item.inTree || void 0,
+            tabIndex: item.inTree ? -1 : void 0,
+            onMouseDown: item.inTree ? (event) => event.preventDefault() : void 0,
+            onClick: (event) => {
+              event.stopPropagation();
+              setExpanded(!expanded);
+            },
+            style: COLUMN_BOX,
+            className: cn(
+              COLUMN_SLOT,
+              // The drawn box stays on --tree-column because that column is also
+              // the indent step; a bigger button moves every name in the tree.
+              hitTargetMin,
+              "rounded-xs text-muted-foreground motion-interactive hover:text-foreground",
+              !expanded && "-rotate-90"
+            ),
+            children: disclosureIcon ?? /* @__PURE__ */ jsx(DisclosureMark, {})
+          }
+        ) : /* @__PURE__ */ jsx("span", { "aria-hidden": true, style: COLUMN_BOX, className: "shrink-0" }),
+        /* @__PURE__ */ jsx("span", { "aria-hidden": true, style: COLUMN_BOX, className: cn(COLUMN_SLOT, "text-muted-foreground"), children: icon }),
+        /* @__PURE__ */ jsx("span", { id: nameId, className: "min-w-0 flex-1 truncate text-ui-md text-foreground", children }),
+        actions ? /* @__PURE__ */ jsx("span", { className: "flex shrink-0 items-center", children: actions }) : null
+      ]
+    }
+  );
+  if (subtree === void 0) return row;
+  return /* @__PURE__ */ jsxs(Fragment, { children: [
+    row,
+    expanded ? /* @__PURE__ */ jsx(TreeDepthContext.Provider, { value: depth + 1, children: subtree }) : null
+  ] });
+}
+TreeRow.displayName = "TreeRow";
+function TreeEmpty({
+  depth: depthProp,
+  message,
+  action,
+  dropTarget = false,
+  className,
+  children,
+  ...props
+}) {
+  const inheritedDepth = useContext(TreeDepthContext);
+  const depth = depthProp ?? inheritedDepth;
+  return /* @__PURE__ */ jsxs(
+    "div",
+    {
+      "data-drop-target": dropTarget || void 0,
+      className: cn(
+        "flex flex-col",
+        dropTarget && "mx-2 my-1 gap-1 rounded-sm border border-dashed border-hairline-strong p-2",
+        className
+      ),
+      ...props,
+      children: [
+        /* @__PURE__ */ jsx(
+          "p",
+          {
+            style: dropTarget ? void 0 : { paddingInlineStart: treeIndent(depth) },
+            className: cn(
+              "flex h-(--control-xs) items-center text-ui-body text-muted-foreground",
+              dropTarget ? "justify-center" : "pe-2"
+            ),
+            children: message
+          }
+        ),
+        action,
+        children
+      ]
+    }
+  );
+}
+TreeEmpty.displayName = "TreeEmpty";
+function TreeAddRow({
+  depth: depthProp,
+  label,
+  icon,
+  className,
+  style,
+  id: idProp,
+  onFocus,
+  ...props
+}) {
+  const inheritedDepth = useContext(TreeDepthContext);
+  const depth = depthProp ?? inheritedDepth;
+  const item = useTreeItem(idProp);
+  return /* @__PURE__ */ jsxs(
+    "button",
+    {
+      type: "button",
+      ...props,
+      id: item.inTree ? item.id : idProp,
+      role: item.inTree ? "treeitem" : void 0,
+      "aria-level": item.inTree ? depth + 1 : void 0,
+      tabIndex: item.tabIndex,
+      onFocus: (event) => {
+        item.claimFocus();
+        onFocus?.(event);
+      },
+      style: { paddingInlineStart: treeIndent(depth), ...style },
+      className: cn(
+        "group flex h-(--control-xs) w-full items-center gap-1.5 rounded-xs pe-1 motion-interactive",
+        "text-ui-md text-muted-foreground hover:bg-panel-raised/60 hover:text-foreground",
+        ITEM_FOCUS,
+        className
+      ),
+      children: [
+        /* @__PURE__ */ jsx("span", { "aria-hidden": true, style: COLUMN_BOX, className: "shrink-0" }),
+        /* @__PURE__ */ jsx("span", { "aria-hidden": true, style: COLUMN_BOX, className: COLUMN_SLOT, children: icon ?? /* @__PURE__ */ jsx(AddMark, {}) }),
+        /* @__PURE__ */ jsx("span", { className: "min-w-0 truncate", children: label })
+      ]
+    }
+  );
+}
+TreeAddRow.displayName = "TreeAddRow";
+export {
+  Tree,
+  TreeAddRow,
+  TreeEmpty,
+  TreeRow,
+  TreeSection,
+  treeIndent
+};