@stacksjs/components 0.2.119 → 0.2.120

package/src/ui/sidebar/rows.ts

@@ -0,0 +1,55 @@
+/**
+ * The shapes a sidebar's rows are described with.
+ *
+ * These live apart from `index.ts` because both the barrel and `spaces.ts`
+ * need them: a space carries sections exactly like a plain sidebar does. With
+ * the definitions in the barrel, the leaf had to import from it and the two
+ * modules formed a cycle — legal for types, but it drags the whole public
+ * surface into any program that touches one small module.
+ *
+ * `index.ts` re-exports everything here, so this split is invisible to callers.
+ *
+ * @module
+ */
+
+/**
+ * One navigation row.
+ *
+ * ```ts
+ * { id: 'icloud', label: 'iCloud', icon: 'i-f7-tray', iconColor: 'blue', count: 248, active: true }
+ * ```
+ */
+export interface SidebarItemData {
+  id: string
+  label: string
+  /** Iconify utility class, e.g. `i-f7-tray`. F7 icons mirror SF Symbols. */
+  icon?: string
+  /** macOS system color name (`"blue"`, `"red"`, `"yellow"`, …) or any CSS color. */
+  iconColor?: string
+  /** Image URL rendered instead of an icon (album art, avatars). */
+  image?: string
+  href?: string
+  /** Right-aligned count — rendered as plain gray text like native macOS. */
+  count?: string | number
+  /** @deprecated Use `count`. */
+  badge?: string | number
+  active?: boolean
+  disabled?: boolean
+  /** Nested rows, indented and collapsible under this one. */
+  children?: SidebarItemData[]
+  /** Show a disclosure chevron even without children. */
+  expandable?: boolean
+  /** Initial disclosure state when the item has children. Defaults to true. */
+  expanded?: boolean
+}
+
+/** A titled group of rows (e.g. "Favorites"). Untitled when `label` is empty. */
+export interface SidebarSectionData {
+  id: string
+  label?: string
+  items: SidebarItemData[]
+  /** Section headers collapse their group on click. Defaults to true. */
+  collapsible?: boolean
+  /** Initial collapse state. Defaults to false (expanded). */
+  collapsed?: boolean
+}

package/src/ui/sidebar/spaces.ts

@@ -0,0 +1,260 @@
+/**
+ * Sidebar spaces — the data side of Arc's swipeable scenes.
+ *
+ * A *space* is a whole sidebar at once: its own pinned tiles, its own folders
+ * and rows, its own bottom action, and — the part that carries the identity —
+ * its own color. Arc stacks them side by side and you swipe horizontally to
+ * move between them. `<SidebarSpaces>` renders that; this module owns
+ * everything about a space that is data rather than markup.
+ *
+ * ## Color is derived, never enumerated
+ *
+ * A space carries one seed color and every surface is mixed from it:
+ *
+ *   from / to  the panel's gradient stops
+ *   ink        the text color the whole space inherits
+ *   accent     the saturated color for the selected switcher icon
+ *
+ * The mixing happens in CSS via `color-mix(in oklab, …)` rather than in
+ * TypeScript, for three reasons. The browser interpolates in a perceptually
+ * even space, so a yellow space and a blue space land at the same apparent
+ * lightness instead of yellow washing out. `tint: 'blue'` (a macOS system
+ * color) and `tint: '#ff6b6b'` (a brand color) go through the identical path,
+ * so there is no second-class citizen. And because the output is a real
+ * `<color>`, the registered custom properties in `Sidebar.stx` can *animate*
+ * it — switching spaces crossfades the panel instead of cutting.
+ *
+ * ## Two palettes, one source
+ *
+ * Every tint resolves to a light and a dark set, and both are written to the
+ * pane as inline custom properties (`--stx-space-light-*`, `--stx-space-dark-*`).
+ * The scoped CSS picks between them under `prefers-color-scheme`. That split
+ * matters: it keeps the appearance switch in CSS, so a space renders correctly
+ * in dark mode on the *server*, before any client script runs.
+ *
+ * @module
+ */
+
+import type { SidebarSectionData } from './rows'
+import { macosColors, type MacosColor } from './themes'
+
+/** The four surfaces a space paints, in one appearance. */
+export interface SidebarSpaceTintColors {
+  /** Top stop of the panel gradient. */
+  from: string
+  /** Bottom stop of the panel gradient. */
+  to: string
+  /** Text color inherited by everything inside the space. */
+  ink: string
+  /** Saturated color for the active switcher icon and focus rings. */
+  accent: string
+}
+
+/** A space's palette in both appearances. */
+export interface SidebarSpaceTint {
+  light: SidebarSpaceTintColors
+  dark: SidebarSpaceTintColors
+}
+
+/** A tile in a space's pinned grid — Arc's favorites row. */
+export interface SidebarPinnedItemData {
+  id: string
+  /** Accessible name. Shown as a tooltip, never as visible text. */
+  label: string
+  /** Iconify utility class, e.g. `i-f7-house-fill`. */
+  icon?: string
+  /** Favicon or artwork URL, rendered instead of an icon. */
+  image?: string
+  /** macOS system color name or any CSS color, applied to `icon`. */
+  iconColor?: string
+  href?: string
+}
+
+/** A single labelled action row (Arc's "+ New Tab", Notes' "+ New Note"). */
+export interface SidebarSpaceActionData {
+  /** Emitted back to the app. Defaults to the space id suffixed with the role. */
+  id?: string
+  label: string
+  /** Iconify utility class. Defaults to a plus for the primary action. */
+  icon?: string
+}
+
+/** One scene in a swipeable sidebar. */
+export interface SidebarSpaceData {
+  id: string
+  /** Title shown above the rows, e.g. "Personal". */
+  label?: string
+  /** Iconify utility class — used for both the title and the switcher rail. */
+  icon?: string
+  /**
+   * Seed color. A macOS system color name (`'blue'`, `'green'`, …), any CSS
+   * color (`'#ff6b6b'`, `'oklch(70% 0.15 20)'`), or a fully specified
+   * {@link SidebarSpaceTint} when you want exact control.
+   */
+  tint?: string | SidebarSpaceTint
+  /** Favorites grid pinned above the rows. */
+  pinned?: SidebarPinnedItemData[]
+  /** Row groups, identical in shape to a plain `<Sidebar>`'s sections. */
+  sections?: SidebarSectionData[]
+  /** Primary action row at the foot of the list. */
+  action?: SidebarSpaceActionData
+  /** Small trailing action on the rule above `action` — Arc's "Clear". */
+  clear?: SidebarSpaceActionData
+}
+
+/** Payload of the `spaceChange` event. */
+export interface SidebarSpaceChangeEvent {
+  id: string
+  index: number
+  /** What moved the sidebar — useful for telling a user gesture from a restore. */
+  source: 'swipe' | 'switcher' | 'keyboard' | 'native' | 'restore' | 'api'
+}
+
+/** A space with its palette resolved and its inline custom properties built. */
+export interface NormalizedSidebarSpace {
+  id: string
+  label: string
+  icon: string
+  pinned: SidebarPinnedItemData[]
+  sections: SidebarSectionData[]
+  action: SidebarSpaceActionData | null
+  clear: SidebarSpaceActionData | null
+  tint: SidebarSpaceTint
+  /** `style` attribute value that publishes this space's palette. */
+  style: string
+}
+
+/**
+ * Neutral seed for spaces that declare no tint. Deliberately the macOS system
+ * gray rather than a literal gray, so an untinted space sits in the same
+ * perceptual family as the tinted ones instead of reading as "broken".
+ */
+const NEUTRAL_SEED = macosColors.gray
+
+function mix(color: string, percent: number, into: string): string {
+  return `color-mix(in oklab, ${color} ${percent}%, ${into})`
+}
+
+/**
+ * Build a full light/dark palette from one seed color.
+ *
+ * The percentages are the tuning surface of the whole feature, so they are
+ * worth stating plainly. In light appearance the panel stays *pale* — 16% and
+ * 34% of the seed — because Arc's spaces are washes, not fills; anything
+ * stronger and the white selection cards stop reading as raised. The ink is
+ * the seed pulled almost to black (22% seed) so text keeps a hint of the
+ * space's hue without losing contrast. In dark appearance the relationship
+ * inverts: the seed is mixed *into* near-black for the panel and *into* white
+ * for the ink and accent, which keeps a dark space recognizably the same color
+ * as its light counterpart rather than a different one.
+ */
+export function deriveSpaceTint(seed: string): SidebarSpaceTint {
+  return {
+    light: {
+      from: mix(seed, 16, '#ffffff'),
+      to: mix(seed, 34, '#ffffff'),
+      ink: mix(seed, 22, '#17171b'),
+      accent: mix(seed, 88, '#2a2a30'),
+    },
+    dark: {
+      from: mix(seed, 26, '#101014'),
+      to: mix(seed, 14, '#08080b'),
+      ink: mix(seed, 12, '#f4f4f7'),
+      accent: mix(seed, 74, '#ffffff'),
+    },
+  }
+}
+
+/**
+ * Resolve a space's `tint` prop to a palette.
+ *
+ * Accepts a macOS system color name, any CSS color, or a pre-built palette.
+ * Unset falls back to the neutral seed.
+ */
+export function resolveSpaceTint(tint?: string | SidebarSpaceTint): SidebarSpaceTint {
+  if (!tint)
+    return deriveSpaceTint(NEUTRAL_SEED)
+  if (typeof tint !== 'string')
+    return tint
+  return deriveSpaceTint(macosColors[tint as MacosColor] || tint)
+}
+
+/**
+ * Render a palette as inline custom properties.
+ *
+ * Both appearances are published at once. `Sidebar.stx` maps them onto the
+ * four registered properties it actually paints with, choosing per
+ * `prefers-color-scheme`, so the correct appearance is already right in the
+ * server-rendered HTML.
+ */
+export function spaceTintVars(tint: SidebarSpaceTint): string {
+  return [
+    `--stx-space-light-from: ${tint.light.from}`,
+    `--stx-space-light-to: ${tint.light.to}`,
+    `--stx-space-light-ink: ${tint.light.ink}`,
+    `--stx-space-light-accent: ${tint.light.accent}`,
+    `--stx-space-dark-from: ${tint.dark.from}`,
+    `--stx-space-dark-to: ${tint.dark.to}`,
+    `--stx-space-dark-ink: ${tint.dark.ink}`,
+    `--stx-space-dark-accent: ${tint.dark.accent}`,
+  ].join('; ')
+}
+
+function normalizeAction(
+  action: SidebarSpaceActionData | undefined,
+  spaceId: string,
+  role: string,
+  fallbackIcon: string,
+): SidebarSpaceActionData | null {
+  if (!action || !action.label)
+    return null
+  return {
+    id: action.id || `${spaceId}-${role}`,
+    label: action.label,
+    icon: action.icon || fallbackIcon,
+  }
+}
+
+/** Normalize one space so template bindings stay plain property reads. */
+export function normalizeSpace(space: SidebarSpaceData): NormalizedSidebarSpace {
+  const tint = resolveSpaceTint(space.tint)
+  return {
+    id: space.id,
+    label: space.label || '',
+    icon: space.icon || '',
+    pinned: space.pinned || [],
+    sections: space.sections || [],
+    action: normalizeAction(space.action, space.id, 'action', 'i-f7-plus'),
+    clear: normalizeAction(space.clear, space.id, 'clear', 'i-f7-arrow-down'),
+    tint,
+    style: spaceTintVars(tint),
+  }
+}
+
+export function normalizeSpaces(spaces: SidebarSpaceData[]): NormalizedSidebarSpace[] {
+  return (spaces || []).map(normalizeSpace)
+}
+
+/**
+ * Index of `id` within `spaces`, or 0 when it is missing.
+ *
+ * Falling back to the first space rather than to -1 is deliberate: a stale
+ * persisted id or a typo should open the sidebar on *something*, never on a
+ * blank track scrolled past its own content.
+ */
+export function spaceIndexOf(spaces: NormalizedSidebarSpace[], id?: string): number {
+  if (!id)
+    return 0
+  const index = spaces.findIndex(space => space.id === id)
+  return index === -1 ? 0 : index
+}
+
+/**
+ * The per-space palettes the client controller needs to repaint the pane.
+ *
+ * Only the colors travel — markup, sections and actions are already in the
+ * DOM, so re-serializing them would just bloat the attribute.
+ */
+export function spaceTintPayload(spaces: NormalizedSidebarSpace[]): SidebarSpaceTint[] {
+  return spaces.map(space => space.tint)
+}

package/src/ui/sidebar/themes.ts

@@ -23,6 +23,11 @@
  * when the window resigns key it falls back to a neutral fill with the label
  * left dark. Icons desaturate to gray in the same non-key state.
  *
+ * The other first-class theme is `arc`, a recreation of the Arc browser's
+ * sidebar. It inverts the macOS selection model — a raised white card on a
+ * warm tinted panel instead of an accent fill on gray — so it uses the
+ * `classes` selection model rather than `accent`. See its own block below.
+ *
  * Legacy themes (`workspace`, `desktop`, `solid`, `transparent`, `vibrancy`)
  * are preserved verbatim from the previous variant maps. `tahoe` now aliases
  * `macos` — it always meant "look like macOS", and now it actually does.
@@ -228,6 +233,108 @@ const desktop: SidebarTheme = {
   },
 }
 
+/**
+ * `arc` — the Arc browser sidebar.
+ *
+ * Where macOS paints the selected row with the system accent, Arc raises it:
+ * the active row becomes a white card floating on a warm tinted panel, with a
+ * hairline border and a single-pixel drop shadow. That inversion — light card
+ * on tinted ground, rather than saturated fill on gray — is the whole look, so
+ * this theme uses the `classes` selection model and puts the card in
+ * `item.active` instead of the accent rules the `accent` model applies.
+ *
+ * Metrics taken from Arc 1.5x at @2x:
+ *
+ *   row pitch 30px with 2px between rows — rows are separate cards, not the
+ *     contiguous run AppKit uses, so consecutive selections read as distinct
+ *   selection radius 8px · white fill · 1px hairline · shadow 0 1px 2px/8%
+ *   label 13px, and the selected row goes to 500 (not 600 — Arc keeps the
+ *     weight shift subtle because the card already carries the emphasis)
+ *   section header 11px medium, sentence case, 55% muted
+ *   icon 16px in an 18px slot · child indent 14px
+ *   panel warm off-white (#f7f5f1), noticeably warmer than macOS's neutral
+ *     #f2f2f4 — the warmth is what makes it read as Arc at a glance
+ *
+ * The panel tint is a soft top-down gradient rather than a flat fill, which is
+ * how Arc suggests the current space's color. Apps that want a per-space tint
+ * can override `--stx-sidebar-tint` on the pane; the gradient falls back to the
+ * warm default when it is unset.
+ */
+const arc: SidebarTheme = {
+  selection: 'classes',
+  pane: [
+    'bg-[#f7f5f1]/92 dark:bg-[#1a1a1c]/92',
+    'backdrop-blur-[40px] backdrop-saturate-[160%]',
+    'text-[#2c2a28] dark:text-[#ededf0]',
+    'select-none',
+  ].join(' '),
+  layers: {
+    // Space tint. `--stx-sidebar-tint` lets an app color the panel per space
+    // the way Arc does; unset, it resolves to a warm neutral wash.
+    tint: [
+      'bg-[linear-gradient(180deg,var(--stx-sidebar-tint,rgba(255,251,242,0.55))_0%,rgba(255,255,255,0)_38%)]',
+      'dark:bg-[linear-gradient(180deg,var(--stx-sidebar-tint,rgba(255,255,255,0.05))_0%,rgba(255,255,255,0)_42%)]',
+    ].join(' '),
+  },
+  scrollArea: 'flex-1 overflow-y-auto overflow-x-hidden px-[8px] pb-[8px]',
+  // Text takes its color from the panel rather than declaring its own, and is
+  // muted with opacity instead. On the plain warm panel `currentColor` is the
+  // pane's own `#2c2a28`, so this renders identically to a hardcoded value —
+  // but inside a space it becomes `--stx-space-ink` and the whole list shifts
+  // hue with the panel on every swipe. Opacity is safe on these because each
+  // is a standalone span; the row itself keeps a solid color, since fading a
+  // row would take its white selection card down with it.
+  sectionHeader: [
+    'group/section flex w-full items-center',
+    'px-[8px] pt-[14px] pb-[4px]',
+    'text-[11px] font-medium leading-[13px]',
+    'opacity-55',
+  ].join(' '),
+  sectionChevron: [
+    'i-f7-chevron-down h-[10px] w-[10px] ml-auto',
+    'opacity-0 group-hover/section:opacity-100 transition-opacity duration-150',
+    'transition-transform duration-200',
+  ].join(' '),
+  // 2px gutter: Arc rows are discrete cards, unlike AppKit's contiguous run.
+  sectionGroup: 'flex flex-col space-y-[2px]',
+  item: {
+    base: [
+      'flex w-full items-center',
+      'h-[30px] rounded-[8px] pl-[6px] pr-[8px]',
+      'text-[13px] leading-[16px] font-normal',
+      'text-current',
+      'transition-[background-color,box-shadow,color] duration-150 ease-out',
+      'cursor-default',
+    ].join(' '),
+    hover: 'hover:bg-white/55 dark:hover:bg-white/8',
+    // The signature: a raised white card rather than an accent fill. The label
+    // stays on the panel ink — Arc does not recolor a selected row, the card
+    // under it carries the emphasis.
+    active: [
+      'bg-white dark:bg-white/14',
+      'font-medium',
+      'shadow-[0_1px_2px_rgba(0,0,0,0.08)] dark:shadow-[0_1px_2px_rgba(0,0,0,0.35)]',
+      'ring-1 ring-black/5 dark:ring-white/8',
+    ].join(' '),
+    pressed: 'active:bg-white/80 dark:active:bg-white/18',
+    disabled: 'opacity-40 pointer-events-none',
+    disclosure: 'flex h-[16px] w-[16px] shrink-0 items-center justify-center',
+    chevron: [
+      'i-f7-chevron-right h-[10px] w-[10px] opacity-45',
+      'transition-transform duration-200 ease-out',
+    ].join(' '),
+    iconSlot: 'flex h-[18px] w-[18px] shrink-0 items-center justify-center mr-[8px]',
+    icon: 'h-[16px] w-[16px]',
+    image: 'h-[18px] w-[18px] rounded-[5px] object-cover shadow-sm',
+    label: 'flex-1 truncate text-left',
+    count: [
+      'ml-[8px] shrink-0 tabular-nums',
+      'text-[12px] leading-[16px] opacity-45',
+    ].join(' '),
+    indentPerLevel: 14,
+  },
+}
+
 const solid: SidebarTheme = {
   ...macos,
   pane: 'bg-stone-100 dark:bg-neutral-900 text-black dark:text-white select-none',
@@ -252,6 +359,7 @@ export const sidebarThemes: Record<string, SidebarTheme> = {
   'tahoe': macos,
   'macos-tahoe': macos,
   'macos-latest': macos,
+  arc,
   workspace,
   desktop,
   solid,