@stacksjs/components 0.2.111 → 0.2.113

package/src/ui/sidebar/SidebarHeader.stx

@@ -0,0 +1,103 @@
+<script server>
+// The window-chrome strip at the top of a macOS sidebar: traffic lights on
+// the left, floating "Liquid Glass" toolbar buttons on the right, and the
+// whole strip acts as a window drag region inside a Craft window.
+export const theme = $props.theme || $props.variant || 'macos'
+export const showWindowControls = $props.showWindowControls ?? true
+export const actions = $props.actions || [] // [{ id, icon, label }]
+export const title = $props.title || ''
+export const subtitle = $props.subtitle || ''
+export const logo = $props.logo || ''
+export const showSearch = $props.showSearch ?? false
+export const searchPlaceholder = $props.searchPlaceholder || 'Search'
+
+export const isMacos = theme === 'macos' || theme === 'tahoe' || theme === 'macos-tahoe' || theme === 'macos-latest'
+
+// Traffic lights: 13px circles, 7px apart, inset ~21px — measured on
+// macOS Tahoe. Colors are Apple's exact stoplight values.
+export const trafficLightClasses = 'h-[13px] w-[13px] rounded-full shadow-[inset_0_0_1px_rgba(0,0,0,0.2)]'
+
+// Floating toolbar button: a 34px glass circle that brightens on hover.
+export const toolbarButtonClasses = [
+  'grid h-[34px] w-[34px] place-items-center rounded-full',
+  'bg-white/55 dark:bg-white/10',
+  'backdrop-blur-xl',
+  'shadow-[0_1px_4px_rgba(0,0,0,0.12),inset_0_0.5px_0_rgba(255,255,255,0.6)]',
+  'text-[#3c3c43]/75 dark:text-[#ebebf5]/75',
+  'transition-colors duration-150',
+  'hover:bg-white/80 dark:hover:bg-white/20',
+  'active:bg-white/95 dark:active:bg-white/25',
+].join(' ')
+</script>
+
+<script client>
+const emit = defineEmits()
+
+function onAction(event) {
+  emit('action', event.currentTarget?.dataset?.sidebarAction || event.target.closest('[data-sidebar-action]')?.dataset.sidebarAction)
+}
+
+function onSearchInput(event) {
+  emit('search', event.target.value)
+}
+
+function onWindowControl(action) {
+  const api = window.craft?.window
+  if (action === 'close') api?.close?.()
+  if (action === 'minimize') api?.minimize?.()
+  if (action === 'zoom') (api?.maximize || api?.zoom)?.call(api)
+  emit('windowControl', action)
+}
+</script>
+
+@if(isMacos)
+  <div class="flex h-[52px] shrink-0 items-center justify-between pl-[21px] pr-[10px] [-webkit-app-region:drag]">
+    @if(showWindowControls)
+      <div class="group/lights flex items-center gap-[7px] [-webkit-app-region:no-drag]">
+        <button type="button" class="{{ trafficLightClasses }} bg-[#ff5f57]" aria-label="Close window" @click="onWindowControl('close')"></button>
+        <button type="button" class="{{ trafficLightClasses }} bg-[#febc2e]" aria-label="Minimize window" @click="onWindowControl('minimize')"></button>
+        <button type="button" class="{{ trafficLightClasses }} bg-[#28c840]" aria-label="Zoom window" @click="onWindowControl('zoom')"></button>
+      </div>
+    @else
+      <span></span>
+    @endif
+
+    <div class="flex items-center gap-[8px] [-webkit-app-region:no-drag]">
+      @foreach(actions as action)
+        <button type="button" class="{{ toolbarButtonClasses }}" aria-label="{{ action.label }}" data-sidebar-action="{{ action.id }}" @click="onAction($event)">
+          <span class="{{ action.icon }} h-[16px] w-[16px]" aria-hidden="true"></span>
+        </button>
+      @endforeach
+      <slot name="actions" />
+    </div>
+  </div>
+
+  @if(showSearch)
+    <div class="shrink-0 px-[10px] pb-[6px]">
+      <div class="relative">
+        <span class="i-f7-search absolute left-[8px] top-1/2 h-[13px] w-[13px] -translate-y-1/2 text-[#3c3c43]/50 dark:text-[#ebebf5]/50" aria-hidden="true"></span>
+        <input
+          type="text"
+          placeholder="{{ searchPlaceholder }}"
+          class="h-[28px] w-full rounded-[8px] border-0 bg-black/5 pl-[26px] pr-[8px] text-[13px] text-black placeholder:text-[#3c3c43]/50 focus:outline-none focus:ring-2 focus:ring-[#0088ff]/60 dark:bg-white/10 dark:text-white dark:placeholder:text-[#ebebf5]/50"
+          @input="onSearchInput($event)"
+        />
+      </div>
+    </div>
+  @endif
+@else
+  <div class="flex h-13 items-center gap-3 border-b border-black/5 px-4 dark:border-white/10">
+    @if(logo)
+      <img src="{{ logo }}" alt="{{ title }}" class="h-8 w-8 rounded-lg object-cover" />
+    @endif
+    <div class="min-w-0">
+      @if(title)
+        <div class="truncate text-sm font-semibold text-black/90 dark:text-white">{{ title }}</div>
+      @endif
+      @if(subtitle)
+        <div class="truncate text-xs text-black/50 dark:text-white/50">{{ subtitle }}</div>
+      @endif
+    </div>
+    <slot name="actions" />
+  </div>
+@endif

package/src/ui/sidebar/SidebarItem.stx

@@ -0,0 +1,90 @@
+<script server>
+import { resolveIconColor, resolveSidebarTheme } from './themes'
+
+export const id = $props.id || ''
+export const label = $props.label || ''
+export const icon = $props.icon || ''
+export const iconColor = $props.iconColor || ''
+export const image = $props.image || ''
+export const href = $props.href || ''
+export const count = $props.count ?? $props.badge ?? ''
+export const active = $props.active ?? false
+export const disabled = $props.disabled ?? false
+export const expandable = $props.expandable ?? false
+export const expanded = $props.expanded ?? true
+export const depth = $props.depth || 0
+export const parents = $props.parents || ''
+export const theme = $props.theme || $props.variant || 'macos'
+
+const themeStyle = resolveSidebarTheme(theme).item
+
+export const rowClasses = [
+  themeStyle.base,
+  disabled ? themeStyle.disabled : themeStyle.hover,
+  disabled ? '' : themeStyle.pressed,
+  active ? themeStyle.active : '',
+].filter(Boolean).join(' ')
+
+export const disclosureClasses = themeStyle.disclosure
+export const chevronClasses = themeStyle.chevron
+export const iconSlotClasses = themeStyle.iconSlot
+export const iconClasses = `${icon} ${themeStyle.icon}`
+export const imageClasses = themeStyle.image
+export const labelClasses = themeStyle.label
+export const countClasses = themeStyle.count
+
+// Nested rows are indented; the icon tint accepts macOS system color names
+// ("blue", "yellow", …) or any CSS color.
+export const indentStyle = depth > 0 ? `padding-left: ${depth * themeStyle.indentPerLevel}px` : ''
+// The tint is published as a custom property rather than `color:` directly.
+// An inline `color` would outrank any stylesheet rule, so a selected row
+// could never turn its icon white the way AppKit does, and toggling
+// selection on the client could not restore the original tint afterwards.
+const tint = resolveIconColor(iconColor)
+export const iconStyle = tint ? `--stx-sidebar-icon: ${tint}` : ''
+export const isLink = Boolean(href) && !disabled
+</script>
+
+<div
+  data-sidebar-row
+  data-item-id="{{ id }}"
+  @if(parents)data-parents="{{ parents }}"@endif
+  @if(expandable)data-expanded="{{ expanded ? 'true' : 'false' }}"@endif
+  @if(indentStyle)style="{{ indentStyle }}"@endif
+>
+  @if(isLink)
+    <a href="{{ href }}" data-sidebar-item data-label="{{ label }}" class="{{ rowClasses }}" @if(active)data-active="true" aria-current="page"@endif>
+      <span class="{{ disclosureClasses }}" @if(expandable)data-sidebar-disclosure role="button" aria-label="Toggle {{ label }}"@endif>
+        @if(expandable)
+          <span data-sidebar-chevron class="{{ chevronClasses }}" aria-hidden="true"></span>
+        @endif
+      </span>
+      @if(image)
+        <span class="{{ iconSlotClasses }}"><img src="{{ image }}" alt="" class="{{ imageClasses }}" /></span>
+      @elseif(icon)
+        <span class="{{ iconSlotClasses }}"><span data-sidebar-icon class="{{ iconClasses }}" @if(iconStyle)style="{{ iconStyle }}"@endif aria-hidden="true"></span></span>
+      @endif
+      <span class="{{ labelClasses }}">{{ label }}</span>
+      @if(count !== '' && count !== null && count !== undefined)
+        <span data-sidebar-count class="{{ countClasses }}">{{ count }}</span>
+      @endif
+    </a>
+  @else
+    <button type="button" data-sidebar-item data-label="{{ label }}" class="{{ rowClasses }}" @if(active)data-active="true" aria-current="page"@endif @if(disabled)data-disabled disabled aria-disabled="true"@endif>
+      <span class="{{ disclosureClasses }}" @if(expandable)data-sidebar-disclosure role="button" aria-label="Toggle {{ label }}"@endif>
+        @if(expandable)
+          <span data-sidebar-chevron class="{{ chevronClasses }}" aria-hidden="true"></span>
+        @endif
+      </span>
+      @if(image)
+        <span class="{{ iconSlotClasses }}"><img src="{{ image }}" alt="" class="{{ imageClasses }}" /></span>
+      @elseif(icon)
+        <span class="{{ iconSlotClasses }}"><span data-sidebar-icon class="{{ iconClasses }}" @if(iconStyle)style="{{ iconStyle }}"@endif aria-hidden="true"></span></span>
+      @endif
+      <span class="{{ labelClasses }}">{{ label }}</span>
+      @if(count !== '' && count !== null && count !== undefined)
+        <span data-sidebar-count class="{{ countClasses }}">{{ count }}</span>
+      @endif
+    </button>
+  @endif
+</div>

package/src/ui/sidebar/SidebarSection.stx

@@ -0,0 +1,83 @@
+<script server>
+import { resolveSidebarTheme } from './themes'
+
+export const id = $props.id || ''
+export const label = $props.label || ''
+export const items = $props.items || []
+export const collapsible = $props.collapsible ?? true
+export const collapsed = $props.collapsed ?? false
+export const theme = $props.theme || $props.variant || 'macos'
+
+const themeStyle = resolveSidebarTheme(theme)
+export const headerClasses = themeStyle.sectionHeader + (collapsible ? ' cursor-default' : '')
+export const chevronClasses = themeStyle.sectionChevron
+export const groupClasses = themeStyle.sectionGroup
+
+// Components can't render themselves recursively, so the item tree is
+// flattened into ready-to-render rows here. Each row remembers its depth
+// and ancestor ids — the Sidebar controller uses those to collapse whole
+// subtrees.
+function flatten(list, depth = 0, parents = []) {
+  return list.flatMap((item) => {
+    const children = item.children || []
+    const row = {
+      id: item.id,
+      label: item.label,
+      icon: item.icon || '',
+      iconColor: item.iconColor || '',
+      image: item.image || '',
+      href: item.href || '',
+      count: item.count ?? item.badge ?? '',
+      active: item.active === true,
+      disabled: item.disabled === true,
+      expandable: children.length > 0 || item.expandable === true,
+      expanded: item.expanded !== false,
+      depth,
+      parents: parents.join('/'),
+    }
+    return [row, ...flatten(children, depth + 1, [...parents, item.id])]
+  })
+}
+
+export const rows = flatten(items)
+</script>
+
+<section
+  data-sidebar-section
+  data-section-id="{{ id }}"
+  data-expanded="{{ collapsed ? 'false' : 'true' }}"
+>
+  @if(label)
+    @if(collapsible)
+      <button type="button" data-sidebar-section-header class="{{ headerClasses }}" aria-expanded="{{ collapsed ? 'false' : 'true' }}">
+        <span class="truncate">{{ label }}</span>
+        <span data-sidebar-section-chevron class="{{ chevronClasses }}" aria-hidden="true"></span>
+      </button>
+    @else
+      <div class="{{ headerClasses }}">
+        <span class="truncate">{{ label }}</span>
+      </div>
+    @endif
+  @endif
+
+  <div class="{{ groupClasses }}" role="group" @if(label)aria-label="{{ label }}"@endif>
+    @foreach(rows as row)
+      <SidebarItem
+        :id="row.id"
+        :label="row.label"
+        :icon="row.icon"
+        :iconColor="row.iconColor"
+        :image="row.image"
+        :href="row.href"
+        :count="row.count"
+        :active="row.active"
+        :disabled="row.disabled"
+        :expandable="row.expandable"
+        :expanded="row.expanded"
+        :depth="row.depth"
+        :parents="row.parents"
+        :theme="theme"
+      />
+    @endforeach
+  </div>
+</section>

package/src/ui/sidebar/index.ts

@@ -0,0 +1,146 @@
+export { default as Sidebar } from './Sidebar.stx'
+export { default as SidebarFooter } from './SidebarFooter.stx'
+export { default as SidebarHeader } from './SidebarHeader.stx'
+export { default as SidebarItem } from './SidebarItem.stx'
+export { default as SidebarSection } from './SidebarSection.stx'
+export * from './themes'
+
+/**
+ * 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
+}
+
+/**
+ * Sidebar themes. `macos` recreates the sidebar of the latest macOS
+ * (Tahoe, macOS 26/27) — translucent material, Liquid Glass edge shimmer,
+ * 30px rows with 9px-radius highlights and plain gray counts. `tahoe`,
+ * `macos-tahoe` and `macos-latest` are aliases of `macos`. The remaining
+ * names are legacy looks kept for backwards compatibility.
+ */
+type MacOSSidebarTheme = 'macos' | 'macos-tahoe' | 'macos-latest' | 'tahoe'
+type LegacySidebarTheme = 'vibrancy' | 'solid' | 'transparent' | 'workspace' | 'desktop'
+export type SidebarThemeChoice = MacOSSidebarTheme | LegacySidebarTheme
+
+export interface SidebarProps {
+  /** Sections with their items. Omit to compose children via the default slot. */
+  sections?: SidebarSectionData[]
+  /** Visual theme. Defaults to `macos`. */
+  theme?: SidebarThemeChoice
+  /** @deprecated Use `theme`. */
+  variant?: SidebarThemeChoice
+  /** Expanded width in pixels. Defaults to 250 (native macOS default). */
+  width?: number
+  position?: 'left' | 'right'
+  /** Layout placement for app shells. Defaults to `fixed`. */
+  placement?: 'fixed' | 'sticky' | 'static'
+  bordered?: boolean
+  /** Whether the sidebar starts collapsed. */
+  collapsed?: boolean
+  collapsible?: boolean
+  /** `hidden` slides away entirely (macOS); `rail` keeps a compact strip. */
+  collapseMode?: 'hidden' | 'rail'
+  /** Rail width when `collapseMode` is `rail`. */
+  minWidth?: number
+  /** localStorage key that persists collapse state. */
+  persistKey?: string
+  /** App-shell selector whose width CSS variable tracks the sidebar. */
+  shellSelector?: string
+  widthVar?: string
+  collapsedClass?: string
+  className?: string
+  onCollapse?: (collapsed: boolean) => void
+  onSectionToggle?: (sectionId: string) => void
+  onItemToggle?: (event: { id: string, expanded: boolean }) => void
+  onItemClick?: (item: SidebarItemData, event: Event) => void
+}
+
+export interface SidebarSectionProps {
+  id: string
+  label?: string
+  items: SidebarItemData[]
+  collapsible?: boolean
+  collapsed?: boolean
+  theme?: SidebarThemeChoice
+}
+
+export interface SidebarItemProps extends SidebarItemData {
+  /** Nesting depth — set by SidebarSection when flattening the tree. */
+  depth?: number
+  /** Slash-joined ancestor ids — set by SidebarSection. */
+  parents?: string
+  theme?: SidebarThemeChoice
+}
+
+/** A floating toolbar or footer action button. */
+export interface SidebarActionData {
+  id: string
+  /** Iconify utility class. */
+  icon: string
+  /** Accessible label. */
+  label: string
+}
+
+export interface SidebarHeaderProps {
+  theme?: SidebarThemeChoice
+  /** Render traffic lights (wired to Craft's window API when present). */
+  showWindowControls?: boolean
+  /** Floating Liquid Glass toolbar buttons on the right. */
+  actions?: SidebarActionData[]
+  showSearch?: boolean
+  searchPlaceholder?: string
+  /** Legacy (non-macos) header content. */
+  title?: string
+  subtitle?: string
+  logo?: string
+  onAction?: (actionId: string) => void
+  onSearch?: (value: string) => void
+  onWindowControl?: (action: 'close' | 'minimize' | 'zoom') => void
+}
+
+export interface SidebarFooterProps {
+  theme?: SidebarThemeChoice
+  /** Account row, like Music's profile footer. */
+  avatar?: string
+  name?: string
+  detail?: string
+  actions?: SidebarActionData[]
+  onProfileClick?: () => void
+  onAction?: (actionId: string) => void
+}