@sableui/react 0.6.1 → 0.7.0

package/dist/components/gliding-highlight/gliding-highlight.meta.js

@@ -0,0 +1,135 @@
+// src/components/gliding-highlight/gliding-highlight.meta.ts
+var glidingHighlightMeta = {
+  name: "GlidingHighlight",
+  summary: "One highlight that travels to the active item, instead of each item toggling its own background. Measured, not assumed, so rows of unequal height stay exact.",
+  status: "stable",
+  keywords: [
+    "highlight",
+    "active",
+    "selection",
+    "indicator",
+    "menu",
+    "list",
+    "glide",
+    "slide",
+    "thumb",
+    "hover"
+  ],
+  usage: {
+    description: "Use GlidingHighlight for a set of items where one is active at a time and the pointer or arrow keys move between them \u2014 a menu, an option list, a command palette, a segmented control. It replaces per-item `hover:bg-*` with a single element that moves.",
+    bestPractices: [
+      {
+        guidance: "do",
+        description: "Pass `hovered ?? selected`. The fallback is what makes the pointer leaving a menu return the highlight to the current choice instead of dropping it, so the reader's place is never lost."
+      },
+      {
+        guidance: "do",
+        description: "Reach for it wherever a list is keyboard-navigable. The gain is largest for arrow keys: a background that teleports between rows makes the eye re-find the highlight at every step, where one that moves can be tracked while it travels \u2014 which is what keeps a long list readable in motion rather than only at rest."
+      },
+      {
+        guidance: "do",
+        description: "Keep selection semantics on the items \u2014 `aria-selected`, `aria-current`, `data-selected`. The highlight is `aria-hidden` decoration over whatever the children already announce."
+      },
+      {
+        guidance: "dont",
+        description: "Do not use it for items that are not mutually exclusive. A travelling highlight says 'one of these, and it is this one'; over a multi-select list it contradicts the checkboxes beside it, and only one of the two can be right."
+      },
+      {
+        guidance: "dont",
+        description: "Do not put non-item chrome among the direct children \u2014 a group heading, a separator, a footer hint. Every direct child is a measurable row, so `active` counts them, and the highlight lands one row off from the index the caller is reasoning about. Wrap the items in their own GlidingHighlight, or move the chrome outside."
+      },
+      {
+        guidance: "dont",
+        description: "Do not drive it from a scroll position or a timer. It is an affordance for a set with a discrete active member; a highlight that moves without an item becoming active reads as the interface selecting things on its own."
+      }
+    ],
+    anatomy: [
+      {
+        name: "Container",
+        required: true,
+        description: "Positioning context for the highlight. Each direct child is measured as one item."
+      },
+      {
+        name: "Highlight",
+        required: true,
+        description: "The travelling element. `aria-hidden`, absolutely positioned, invisible until something is active."
+      }
+    ]
+  },
+  related: {
+    components: ["Menu", "Select", "Combobox", "CommandMenu", "SideNav"]
+  },
+  props: [
+    {
+      name: "active",
+      type: "number | null",
+      description: "Index of the item the highlight sits behind, or `null` for none. Pass `hovered ?? selected`."
+    },
+    {
+      name: "orientation",
+      type: '"vertical" | "horizontal"',
+      description: "Deprecated and ignored: the highlight measures both axes, so a horizontal row needs no flag.",
+      deprecated: "nothing \u2014 omit it"
+    },
+    {
+      name: "onPointerLeave",
+      type: "PointerEventHandler (and every other div prop)",
+      description: "The container is a plain div, so its props pass through. For a hover-following list, reset the hovered index here so the highlight returns to the selected row when the pointer leaves."
+    },
+    {
+      name: "highlightClassName",
+      type: "string",
+      description: "Class for the travelling highlight itself, for changing its fill or radius. The radius defaults to `sable-frame-inner`, so inside a `sable-frame` container it nests concentrically; in any other rounded, inset container pass `rounded-concentric-<outer>/<inset>` here and on the rows. The container's own `className` styles the list."
+    }
+  ],
+  tokensUsed: ["accent"],
+  motion: [
+    {
+      slot: "arrival",
+      recipe: "none",
+      part: "Highlight",
+      why: "It deliberately does not animate in. Fading it up at rest position \u2014 usually row 0 \u2014 makes a menu look like it opened with the first item pre-selected, which is a claim about state that is not true. It stays invisible until something is genuinely active."
+    },
+    {
+      slot: "response",
+      recipe: "none",
+      part: "Container",
+      why: "The container is not the control; the items are, and they own their own pointer states. This draws the result."
+    },
+    {
+      slot: "transition",
+      recipe: "motion-interactive",
+      part: "Highlight",
+      why: "The travel IS the component \u2014 a highlight that jumps is just a background toggle with extra machinery. Position, size and opacity ride one declaration so a tall row's height cannot catch up after its position has, which would read as the highlight stretching into place rather than moving."
+    },
+    {
+      slot: "activity",
+      recipe: "none",
+      part: "Highlight",
+      why: "Nothing here is indeterminate. A list still loading its options shows a Skeleton in place of the rows."
+    }
+  ],
+  a11y: [
+    "The highlight is `aria-hidden` and carries no semantics \u2014 it renders selection, it does not declare it. Keep `aria-selected` / `aria-current` on the items themselves.",
+    "Pointer-free by construction (`pointer-events-none`), so it can never intercept a click meant for the item beneath it.",
+    "Works with roving-tabindex and `aria-activedescendant` lists alike: it reads an index the caller already owns, and does not manage focus.",
+    "Under reduced motion or with MotionProvider off, the highlight moves instantly rather than gliding \u2014 the active item is still shown, which is the part that carries meaning."
+  ],
+  examples: [
+    {
+      label: "A hoverable menu, returning home on leave",
+      code: '<GlidingHighlight active={hovered ?? selected} className="sable-frame sable-surface sable-surface-popover sable-frame-popover" onPointerLeave={() => setHovered(null)}>{items.map((item, i) => (<button key={item.id} type="button" className="sable-frame-inner px-2 py-1.5 text-start" onPointerEnter={() => setHovered(i)} onClick={() => setSelected(i)}>{item.label}</button>))}</GlidingHighlight>'
+    },
+    {
+      label: "Horizontal, as a segmented control",
+      code: '<GlidingHighlight active={tab} className="sable-well flex gap-1 rounded-md p-1" highlightClassName="rounded-concentric-md/1">{tabs.map((t, i) => (<button key={t} type="button" className="rounded-concentric-md/1 px-3 py-1" onClick={() => setTab(i)}>{t}</button>))}</GlidingHighlight>'
+    },
+    {
+      label: "Keyboard navigation \u2014 the case it exists for",
+      code: '<GlidingHighlight active={cursor} onKeyDown={(e) => { if (e.key === "ArrowDown") setCursor((c) => (c + 1) % rows.length) }}>{rows.map((r) => (<div key={r.id} role="option" aria-selected={false}>{r.label}</div>))}</GlidingHighlight>'
+    }
+  ]
+};
+export {
+  glidingHighlightMeta
+};

package/dist/components/gliding-highlight/index.js

@@ -0,0 +1,9 @@
+// src/components/gliding-highlight/index.ts
+import {
+  GlidingHighlight
+} from "./gliding-highlight.js";
+import { glidingHighlightMeta } from "./gliding-highlight.meta.js";
+export {
+  GlidingHighlight,
+  glidingHighlightMeta
+};

package/dist/components/gradient-art/gradient-art.js

@@ -0,0 +1,168 @@
+"use client";
+
+// src/components/gradient-art/gradient-art.tsx
+import { useEffect, useRef } from "react";
+import { cn } from "../../lib/cn.js";
+import { jsx, jsxs } from "react/jsx-runtime";
+var ART_SLOTS = ["var(--art-1)", "var(--art-2)", "var(--art-3)", "var(--art-4)", "var(--art-5)", "var(--art-6)"];
+var ART_GROUND = "var(--art-ground)";
+var lifted = (tone) => `oklch(from var(--tone-${tone}) clamp(0.5, calc(l + 0.16), 0.9) max(calc(c * 1.25), 0.1) h)`;
+var ground = (tone) => `color-mix(in oklab, var(--primary) 55%, oklch(from var(--tone-${tone}) 0.3 c h))`;
+function seedValue(seed) {
+  if (seed == null) return 0.37;
+  if (typeof seed === "number") return Math.abs(seed * 0.618034) % 1;
+  let hash = 2166136261;
+  for (let i = 0; i < seed.length; i++) {
+    hash ^= seed.charCodeAt(i);
+    hash = Math.imul(hash, 16777619);
+  }
+  return (hash >>> 0) / 4294967296;
+}
+function fallback(palette, groundColor, seed) {
+  const spots = palette.map((color, i) => {
+    const angle = (seed + i / palette.length) * Math.PI * 2;
+    const x = Math.round(50 + Math.cos(angle) * 38);
+    const y = Math.round(50 + Math.sin(angle) * 38);
+    return `radial-gradient(in oklab at ${x}% ${y}%, ${color}, transparent 60%)`;
+  });
+  return [...spots, groundColor].join(", ");
+}
+function rotate(items, seed) {
+  if (items.length < 2) return [...items];
+  const shift = Math.floor(seed * 7919) % items.length;
+  return [...items.slice(shift), ...items.slice(0, shift)];
+}
+var HUE_TURN = 20;
+var LIGHT_STEP = 0.04;
+function nudge(color, seed) {
+  const frac = (n) => n - Math.floor(n);
+  const dh = ((frac(seed * 7.31) * 2 - 1) * HUE_TURN).toFixed(1);
+  const dl = ((frac(seed * 13.7) * 2 - 1) * LIGHT_STEP).toFixed(3);
+  return `oklch(from ${color} clamp(0, calc(l + ${dl}), 1) c calc(h + ${dh}))`;
+}
+function param(style, name, fallbackValue) {
+  const n = Number.parseFloat(style.getPropertyValue(name));
+  return Number.isFinite(n) ? Math.min(1, Math.max(0, n)) : fallbackValue;
+}
+var MAX_PIXELS = 15e5;
+function GradientArt({ variant = "mesh", tones, seed, className, style, children, ...props }) {
+  const root = useRef(null);
+  const canvas = useRef(null);
+  const probes = useRef(null);
+  const value = seedValue(seed);
+  const palette = (tones?.length ? tones.map(lifted) : ART_SLOTS).map((color) => nudge(color, value));
+  const groundColor = nudge(tones?.length ? ground(tones[0]) : ART_GROUND, value);
+  const paletteKey = palette.join(" ");
+  const background = fallback(rotate(palette, value), groundColor, value);
+  useEffect(() => {
+    const element = root.current;
+    const target = canvas.current;
+    const swatches = probes.current;
+    if (!element || !target || !swatches) return;
+    if (typeof IntersectionObserver === "undefined" || typeof ResizeObserver === "undefined") return;
+    let cancelled = false;
+    let teardown;
+    import("./renderer.js").then(
+      (renderer) => {
+        if (!cancelled) teardown = start(renderer);
+      },
+      () => {
+      }
+    );
+    return () => {
+      cancelled = true;
+      teardown?.();
+    };
+    function start({ artSupported, cssColorToRgba, onArtInvalidate, onThemeChange, paintArt }) {
+      if (!element || !target || !swatches || !artSupported()) return;
+      let visible = false;
+      let frame = 0;
+      let last = "";
+      const paint = () => {
+        frame = 0;
+        if (!visible) return;
+        const rect = element.getBoundingClientRect();
+        if (!rect.width || !rect.height) return;
+        let ratio = Math.min(window.devicePixelRatio || 1, 2);
+        const pixels = rect.width * rect.height * ratio * ratio;
+        if (pixels > MAX_PIXELS) ratio *= Math.sqrt(MAX_PIXELS / pixels);
+        const width = Math.max(1, Math.round(rect.width * ratio));
+        const height = Math.max(1, Math.round(rect.height * ratio));
+        const resolve = (probe) => cssColorToRgba(getComputedStyle(probe).color);
+        const [groundProbe, ...colorProbes] = Array.from(swatches.children);
+        const colors = rotate(
+          colorProbes.map(resolve).filter((c) => c != null && c[3] > 0.01),
+          value
+        );
+        const groundRgba = groundProbe ? resolve(groundProbe) : null;
+        if (!colors.length) return;
+        const own = getComputedStyle(element);
+        const character = { warp: param(own, "--art-warp", 0.8), softness: param(own, "--art-softness", 0.88), grain: param(own, "--art-grain", 0) };
+        const key = JSON.stringify([variant, value, width, height, colors, groundRgba, character]);
+        if (key === last) return;
+        const ordered = variant === "grain" && groundRgba ? [groundRgba, ...colors] : colors;
+        if (paintArt(target, { variant, colors: ordered, seed: value, width, height, pixelRatio: ratio, ...character })) {
+          last = key;
+          target.dataset.painted = "";
+        }
+      };
+      const schedule = () => {
+        if (!frame) frame = requestAnimationFrame(paint);
+      };
+      const repaint = () => {
+        last = "";
+        schedule();
+      };
+      const intersection = new IntersectionObserver(
+        ([entry]) => {
+          visible = entry.isIntersecting;
+          if (visible) schedule();
+        },
+        { rootMargin: "200px" }
+      );
+      intersection.observe(element);
+      const resize = new ResizeObserver(schedule);
+      resize.observe(element);
+      const offTheme = onThemeChange(schedule);
+      const offInvalidate = onArtInvalidate(repaint);
+      return () => {
+        cancelAnimationFrame(frame);
+        intersection.disconnect();
+        resize.disconnect();
+        offTheme();
+        offInvalidate();
+      };
+    }
+  }, [variant, value, paletteKey]);
+  return /* @__PURE__ */ jsxs(
+    "div",
+    {
+      ref: root,
+      "data-slot": "gradient-art",
+      "data-variant": variant,
+      className: cn("relative isolate overflow-hidden", className),
+      style: { background, ...style },
+      ...props,
+      children: [
+        /* @__PURE__ */ jsx(
+          "canvas",
+          {
+            ref: canvas,
+            "aria-hidden": true,
+            className: "pointer-events-none absolute inset-0 -z-10 size-full opacity-0 motion-interactive data-[painted]:opacity-100",
+            style: { transitionProperty: "opacity" }
+          }
+        ),
+        /* @__PURE__ */ jsxs("span", { ref: probes, hidden: true, children: [
+          /* @__PURE__ */ jsx("span", { style: { color: groundColor } }),
+          palette.map((color) => /* @__PURE__ */ jsx("span", { style: { color } }, color))
+        ] }),
+        children
+      ]
+    }
+  );
+}
+GradientArt.displayName = "GradientArt";
+export {
+  GradientArt
+};

package/dist/components/gradient-art/gradient-art.meta.js

@@ -0,0 +1,81 @@
+// src/components/gradient-art/gradient-art.meta.ts
+var gradientArtMeta = {
+  name: "GradientArt",
+  summary: "Placeholder artwork painted by a static WebGL shader from the preset's own art direction (the --art-* tokens: palette, ground, warp, softness, grain) \u2014 Ember burns, Prism airbrushes, Meridian is grainy monochrome \u2014 with a CSS gradient underneath for prerendered pages and browsers without WebGL2.",
+  status: "beta",
+  keywords: ["gradient", "mesh gradient", "grain", "shader", "artwork", "placeholder image", "cover", "banner", "avatar fallback", "generative"],
+  usage: {
+    description: "Use GradientArt where a real image belongs but none exists yet, or where the image is decoration: a product cover before upload, a profile banner, an album tile, an avatar with no photo. It reads the theme's own tokens, so it follows every preset, mode and live edit; `seed` fixes each item's composition so a list of covers or avatars stays individually recognisable.",
+    bestPractices: [
+      {
+        guidance: "do",
+        description: "Pass a stable `seed` per item \u2014 the name for an avatar, the title for a cover. Each item then keeps the same art across renders, reloads and themes, which is what lets someone recognise it."
+      },
+      {
+        guidance: "do",
+        description: "Size it with layout classes (`aspect-[4/3]`, `h-20`, `size-10 rounded-full`) and put any glyph or initials inside as children; they render above the art."
+      },
+      {
+        guidance: "do",
+        description: "Keep the default `mesh` for covers, tiles and avatars. Reach for `grain` where a printed, tactile surface suits \u2014 a banner, a hero card \u2014 and keep one variant per surface type so art reads as a system."
+      },
+      {
+        guidance: "dont",
+        description: "Do not put body text over it. The art spans the palette's lightest and most saturated tones, so no single ink is guaranteed to clear contrast across it; reserve overlays for a short label on a scrim or an avatar's initials."
+      },
+      {
+        guidance: "dont",
+        description: "Do not pass colours, and reach for `tones` rarely. The art follows the preset's --art-* tokens on purpose; to change how a product's art looks, set the --theme-art-* hooks in its theme or preset, so every cover, banner and avatar changes together."
+      },
+      {
+        guidance: "dont",
+        description: "Do not use it as a page or hero background. It paints at the element's pixel size, so a full-viewport instance costs a large frame on every theme change; it is sized for covers, banners and tiles."
+      }
+    ]
+  },
+  related: { components: ["Avatar", "Card", "AspectBox"] },
+  props: [
+    { name: "variant", type: '"mesh" | "grain"', default: '"mesh"', description: "mesh: soft spots of colour pulled together by gentle waves. grain: glowing light over deep corners with a printed texture." },
+    {
+      name: "tones",
+      type: '("info" | "standard" | "collectible" | "edition" | "warning")[]',
+      description: "Paint these `--tone-*` colours instead of the preset's art palette. Leave unset to follow the preset's art direction."
+    },
+    { name: "seed", type: "string | number", description: "Fixes the composition: the same seed paints the same art in every theme. Pass a stable id." },
+    { name: "children", type: "ReactNode", description: "Rendered above the art \u2014 initials, a glyph, a short label." },
+    { name: "className", type: "string", description: "Size and shape: aspect, height, rounding." }
+  ],
+  variants: { variant: ["mesh", "grain"] },
+  tokensUsed: ["art-1", "art-2", "art-3", "art-4", "art-5", "art-6", "art-ground", "art-warp", "art-softness", "art-grain", "primary", "tone-info", "tone-standard", "tone-collectible", "tone-edition", "tone-warning"],
+  motion: [
+    {
+      slot: "arrival",
+      recipe: "motion-interactive",
+      part: "canvas",
+      why: "The shader frame fades in over the CSS gradient it replaces, so the swap from fallback to shader reads as the art settling rather than a flash."
+    },
+    { slot: "response", recipe: "none", part: "root", why: "Artwork, not a control: it does not react to the pointer." },
+    {
+      slot: "transition",
+      recipe: "custom",
+      part: "canvas",
+      why: "A theme change repaints the frame in place on the next animation frame; there are no states to move between."
+    },
+    { slot: "activity", recipe: "none", part: "root", why: "Static by design: nothing animates between paints, so it costs nothing while idle and respects reduced motion without a branch." }
+  ],
+  a11y: [
+    "Decorative by default: the canvas is aria-hidden. When the art stands for something (an avatar), label the element that contains it, not the art.",
+    "Children render above the art in the normal reading order, so initials or a label are announced as usual."
+  ],
+  examples: [
+    { label: "Product cover", code: '<GradientArt seed="Untitled (gold rush)" className="aspect-[4/3] rounded-lg" />' },
+    { label: "Grain banner", code: '<GradientArt variant="grain" seed="juno" tones={["info", "edition"]} className="h-20 rounded-md" />' },
+    {
+      label: "Avatar with initials",
+      code: '<GradientArt seed="Mara Okafor" className="grid size-10 place-items-center rounded-full text-label-md text-overlay-foreground">MO</GradientArt>'
+    }
+  ]
+};
+export {
+  gradientArtMeta
+};

package/dist/components/gradient-art/index.js

@@ -0,0 +1,7 @@
+// src/components/gradient-art/index.ts
+import { GradientArt } from "./gradient-art.js";
+import { gradientArtMeta } from "./gradient-art.meta.js";
+export {
+  GradientArt,
+  gradientArtMeta
+};