@ds-mo/ui 1.0.1 → 1.1.0

package/src/wc/components/Sidebar/Sidebar.tsx

@@ -0,0 +1,245 @@
+import { Component, Prop, State, Event, EventEmitter, Element, Watch, h, Host } from '@stencil/core';
+
+export type SidebarWidth = 'mini' | 'default' | number;
+
+const MINI_WIDTH = 56;
+const DEFAULT_WIDTH = 240;
+const MAX_WIDTH = 480;
+const MIN_DRAG_WIDTH = 180;
+const SNAP_THRESHOLD = 140;
+const KEYBOARD_STEP = 16;
+
+const FOCUSABLE_SEL = [
+  'a[href]',
+  'button:not([disabled])',
+  'input:not([disabled])',
+  'select:not([disabled])',
+  'textarea:not([disabled])',
+  '[tabindex]:not([tabindex="-1"])',
+].join(',');
+
+@Component({
+  tag: 'ds-sidebar',
+  styleUrl: 'Sidebar.css',
+  scoped: true,
+})
+export class Sidebar {
+  @Element() el!: HTMLElement;
+
+  @Prop({ mutable: true }) collapsed: boolean = false;
+  @Prop() width: SidebarWidth = 'default';
+  @Prop() resizable: boolean = true;
+  @Prop() mobile: boolean = false;
+
+  @State() private isResizing: boolean = false;
+
+  @Event() dsToggle!: EventEmitter<void>;
+  @Event() dsWidthChange!: EventEmitter<SidebarWidth>;
+
+  private triggerEl: HTMLElement | null = null;
+  private escapeHandler: ((e: KeyboardEvent) => void) | null = null;
+  private tabHandler: ((e: KeyboardEvent) => void) | null = null;
+  private mouseMoveHandler: ((e: MouseEvent) => void) | null = null;
+  private mouseUpHandler: (() => void) | null = null;
+
+  private get resolvedWidth(): number {
+    if (this.width === 'mini') return MINI_WIDTH;
+    if (this.width === 'default') return DEFAULT_WIDTH;
+    return this.width as number;
+  }
+
+  private get isMobileOpen(): boolean {
+    return this.mobile && !this.collapsed;
+  }
+
+  @Watch('collapsed')
+  onCollapsedChange() {
+    if (this.isMobileOpen) {
+      this.setupMobileFocusTrap();
+    } else {
+      this.teardownMobileFocusTrap();
+    }
+  }
+
+  componentDidLoad() {
+    if (this.isMobileOpen) {
+      this.setupMobileFocusTrap();
+    }
+    if (this.mobile) {
+      this.escapeHandler = (e: KeyboardEvent) => {
+        if (e.key === 'Escape' && !this.collapsed) {
+          this.dsToggle.emit();
+        }
+      };
+      document.addEventListener('keydown', this.escapeHandler);
+    }
+  }
+
+  disconnectedCallback() {
+    this.teardownMobileFocusTrap();
+    if (this.escapeHandler) {
+      document.removeEventListener('keydown', this.escapeHandler);
+      this.escapeHandler = null;
+    }
+    this.cleanupMouseHandlers();
+  }
+
+  private setupMobileFocusTrap() {
+    this.triggerEl = document.activeElement as HTMLElement | null;
+
+    const focusables = () =>
+      Array.from(this.el.querySelectorAll<HTMLElement>(FOCUSABLE_SEL)).filter(
+        el => !el.hasAttribute('aria-hidden') && el.offsetParent !== null,
+      );
+
+    const initial = focusables();
+    (initial[0] ?? this.el).focus();
+
+    this.tabHandler = (e: KeyboardEvent) => {
+      if (e.key !== 'Tab') return;
+      const items = focusables();
+      if (!items.length) { e.preventDefault(); this.el.focus(); return; }
+      const first = items[0];
+      const last = items[items.length - 1];
+      const active = document.activeElement as HTMLElement | null;
+      if (e.shiftKey && (active === first || !this.el.contains(active))) {
+        e.preventDefault(); last.focus();
+      } else if (!e.shiftKey && (active === last || !this.el.contains(active))) {
+        e.preventDefault(); first.focus();
+      }
+    };
+    document.addEventListener('keydown', this.tabHandler);
+  }
+
+  private teardownMobileFocusTrap() {
+    if (this.tabHandler) {
+      document.removeEventListener('keydown', this.tabHandler);
+      this.tabHandler = null;
+    }
+    this.triggerEl?.focus?.();
+    this.triggerEl = null;
+  }
+
+  private cleanupMouseHandlers() {
+    if (this.mouseMoveHandler) document.removeEventListener('mousemove', this.mouseMoveHandler);
+    if (this.mouseUpHandler) document.removeEventListener('mouseup', this.mouseUpHandler);
+    this.mouseMoveHandler = null;
+    this.mouseUpHandler = null;
+    document.body.style.cursor = '';
+    document.body.style.userSelect = '';
+  }
+
+  private handleResizeMouseDown(e: MouseEvent) {
+    if (!this.resizable) return;
+    e.preventDefault();
+    this.isResizing = true;
+
+    this.mouseMoveHandler = (ev: MouseEvent) => {
+      const newW = ev.clientX;
+      if (newW < SNAP_THRESHOLD) {
+        this.dsWidthChange.emit('mini');
+      } else if (newW < MIN_DRAG_WIDTH) {
+        this.dsWidthChange.emit('default');
+      } else {
+        this.dsWidthChange.emit(newW);
+      }
+    };
+
+    this.mouseUpHandler = () => {
+      this.isResizing = false;
+      this.cleanupMouseHandlers();
+    };
+
+    document.body.style.cursor = 'col-resize';
+    document.body.style.userSelect = 'none';
+    document.addEventListener('mousemove', this.mouseMoveHandler);
+    document.addEventListener('mouseup', this.mouseUpHandler);
+  }
+
+  private handleResizeKeyDown(e: KeyboardEvent) {
+    if (!this.resizable) return;
+    const w = this.width;
+    const resolved = this.resolvedWidth;
+
+    switch (e.key) {
+      case 'ArrowLeft': {
+        e.preventDefault();
+        if (w === 'mini') return;
+        const next = resolved - KEYBOARD_STEP;
+        this.dsWidthChange.emit(next < MIN_DRAG_WIDTH ? 'mini' : next);
+        break;
+      }
+      case 'ArrowRight': {
+        e.preventDefault();
+        if (w === 'mini') { this.dsWidthChange.emit('default'); return; }
+        this.dsWidthChange.emit(Math.min(resolved + KEYBOARD_STEP, MAX_WIDTH));
+        break;
+      }
+      case 'Home':
+        e.preventDefault();
+        this.dsWidthChange.emit('mini');
+        break;
+      case 'End':
+        e.preventDefault();
+        this.dsWidthChange.emit(MAX_WIDTH);
+        break;
+    }
+  }
+
+  render() {
+    if (this.collapsed && !this.mobile) return null;
+
+    const isMini = this.width === 'mini';
+    const isMobileOpen = this.isMobileOpen;
+    const sidebarWidth = this.collapsed ? 0 : this.resolvedWidth;
+
+    const dialogProps = isMobileOpen
+      ? { role: 'dialog', 'aria-modal': 'true', tabIndex: -1 }
+      : { role: 'navigation' };
+
+    return (
+      <Host>
+        {this.mobile && !this.collapsed && (
+          <div
+            class="backdrop"
+            onClick={() => this.dsToggle.emit()}
+            aria-hidden="true"
+          />
+        )}
+        <aside
+          class={{
+            sidebar: true,
+            'sidebar--mini': isMini,
+            'sidebar--mobile': this.mobile,
+            'sidebar--collapsed': this.collapsed,
+            'sidebar--resizing': this.isResizing,
+          }}
+          style={{ width: `${sidebarWidth}px` }}
+          aria-label="Sidebar"
+          {...dialogProps}
+        >
+          <div class="sidebar__content">
+            <slot />
+          </div>
+          <div class="sidebar__footer">
+            <slot name="footer" />
+          </div>
+          {this.resizable && !this.mobile && (
+            <div
+              class="sidebar__resize-handle"
+              onMouseDown={(e: MouseEvent) => this.handleResizeMouseDown(e)}
+              onKeyDown={(e: KeyboardEvent) => this.handleResizeKeyDown(e)}
+              role="separator"
+              aria-orientation="vertical"
+              aria-label="Resize sidebar"
+              aria-valuenow={this.resolvedWidth}
+              aria-valuemin={MINI_WIDTH}
+              aria-valuemax={MAX_WIDTH}
+              tabIndex={0}
+            />
+          )}
+        </aside>
+      </Host>
+    );
+  }
+}

package/src/wc/components/Skeleton/Skeleton.tsx

@@ -0,0 +1,64 @@
+import { Component, Prop, h, Host } from '@stencil/core';
+
+export type SkeletonVariant = 'text' | 'circular' | 'rectangular';
+
+@Component({
+  tag: 'ds-skeleton',
+  styleUrl: 'Skeleton.css',
+  shadow: true,
+})
+export class Skeleton {
+  @Prop() variant: SkeletonVariant = 'text';
+  /** Width as a CSS value string (e.g. '200px', '100%') or number (px). */
+  @Prop() width: string | number | undefined;
+  /** Height as a CSS value string or number (px). */
+  @Prop() height: string | number | undefined;
+  /** Number of text lines. Only used when variant is 'text'. */
+  @Prop() lines: number = 1;
+  /** Whether to show the shimmer animation. */
+  @Prop() shimmer: boolean = true;
+
+  private get widthCss() {
+    const v = this.width;
+    if (v == null) return undefined;
+    return typeof v === 'number' ? `${v}px` : v;
+  }
+
+  private get heightCss() {
+    const v = this.height;
+    if (v == null) return undefined;
+    return typeof v === 'number' ? `${v}px` : v;
+  }
+
+  render() {
+    if (this.variant === 'text' && this.lines > 1) {
+      return (
+        <Host aria-hidden="true" style={{ width: this.widthCss }}>
+          <div class="text-group">
+            {Array.from({ length: this.lines }, (_, lineIdx) => (
+              <div
+                class={{ skeleton: true, text: true, animate: this.shimmer }}
+                style={{
+                  width: lineIdx === this.lines - 1 ? '60%' : '100%',
+                  height: this.heightCss,
+                }}
+              />
+            ))}
+          </div>
+        </Host>
+      );
+    }
+
+    return (
+      <Host
+        aria-hidden="true"
+        class={{
+          skeleton: true,
+          [this.variant]: true,
+          animate: this.shimmer,
+        }}
+        style={{ width: this.widthCss, height: this.heightCss }}
+      />
+    );
+  }
+}

package/src/wc/components/Skeleton/index.ts

@@ -0,0 +1 @@
+export type { SkeletonVariant } from './Skeleton';

package/src/wc/components/Slider/Slider.tsx

@@ -0,0 +1,68 @@
+import { Component, Prop, Event, EventEmitter, h, Host } from '@stencil/core';
+
+let idCounter = 0;
+
+@Component({
+  tag: 'ds-slider',
+  styleUrl: 'Slider.css',
+  scoped: true,
+})
+export class Slider {
+  private generatedId = `ds-slider-${++idCounter}`;
+
+  @Prop() value: number = 0;
+  @Prop() min: number = 0;
+  @Prop() max: number = 100;
+  @Prop() step: number = 1;
+  @Prop() label!: string;
+  @Prop() inactive: boolean = false;
+  @Prop() valueText: string | undefined;
+  /** Associates with an external <label>. Defaults to an auto-generated ID. */
+  @Prop() inputId: string | undefined;
+
+  @Event() dsChange!: EventEmitter<number>;
+
+  private handleInput = (e: Event) => {
+    this.dsChange.emit(Number((e.target as HTMLInputElement).value));
+  };
+
+  private get pct() {
+    const range = this.max - this.min;
+    return range === 0 ? 0 : Math.round(((this.value - this.min) / range) * 100);
+  }
+
+  render() {
+    const finalId = this.inputId ?? this.generatedId;
+    const pct = this.pct;
+
+    return (
+      <Host class="field">
+        <div class="label-row">
+          <label class="text-body-small-emphasis" htmlFor={finalId}>{this.label}</label>
+          <span class="text-body-small-emphasis">{this.value}</span>
+        </div>
+        <div
+          class={{ track: true, 'track--inactive': this.inactive, 'track--at-min': pct === 0 }}
+          style={{ '--slider-pct': String(pct) } as Record<string, string>}
+        >
+          <div class="track-inner">
+            <div class="fill-track"><div class="fill" /></div>
+            <div class="thumb" />
+          </div>
+          <input
+            type="range"
+            id={finalId}
+            min={this.min}
+            max={this.max}
+            step={this.step}
+            value={this.value}
+            disabled={this.inactive}
+            class="range-input"
+            aria-valuetext={this.valueText}
+            onInput={this.handleInput}
+          />
+        </div>
+      </Host>
+    );
+  }
+}

package/src/wc/components/Slider/index.ts

@@ -0,0 +1 @@
+export type { } from './Slider';

package/src/wc/components/Surface/Surface.tsx

@@ -0,0 +1,81 @@
+import { Component, Prop, h, Host } from '@stencil/core';
+
+export type SurfaceIntent =
+  | 'brand' | 'positive' | 'negative' | 'warning' | 'caution'
+  | 'ai' | 'neutral' | 'walkthrough' | 'guide';
+export type SurfaceBackground = 'primary' | 'secondary' | 'transparent' | 'translucent';
+export type SurfaceContrast = 'faint' | 'medium' | 'bold' | 'strong';
+export type SurfaceElevation =
+  | 'none' | 'depressed' | 'depressed-md' | 'flat' | 'elevated' | 'floating'
+  | 'overlayTop' | 'overlayRight' | 'overlayBottom' | 'overlayLeft';
+export type SurfaceEdge = 'top' | 'right' | 'bottom' | 'left';
+export type SurfaceRadius = 'none' | 'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl' | 'full' | (string & {});
+export type SurfaceElement = 'div' | 'section' | 'aside' | 'article' | 'header' | 'footer' | 'main' | 'nav' | 'span';
+
+const RADIUS_PRESETS = new Set(['none', 'xs', 'sm', 'md', 'lg', 'xl', '2xl', 'full']);
+
+@Component({
+  tag: 'ds-surface',
+  styleUrl: 'Surface.css',
+  scoped: true,
+})
+export class Surface {
+  @Prop() background: SurfaceBackground = 'transparent';
+  @Prop() intent: SurfaceIntent | undefined;
+  @Prop() contrast: SurfaceContrast = 'faint';
+  @Prop() elevation: SurfaceElevation = 'none';
+  /** Space-separated list of edges: "top bottom" etc. Only applies when elevation='none'. */
+  @Prop() edge: string | undefined;
+  @Prop() radius: SurfaceRadius | undefined;
+  @Prop() interactive: boolean = false;
+  @Prop() selected: boolean = false;
+  @Prop() inactive: boolean = false;
+  @Prop() as: SurfaceElement = 'div';
+
+  render() {
+    // Polymorphic element: TSX treats a variable tag as a component, so a
+    // dynamic intrinsic element name must be cast to `any` to render.
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const Tag = this.as as any;
+
+    const intentClass = this.intent
+      ? `intent-${this.intent}-${this.contrast}`
+      : `bg-${this.background}`;
+
+    const elevClass = `elevation-${this.elevation}`;
+
+    const edgeClasses = this.edge && this.elevation === 'none'
+      ? this.edge.trim().split(/\s+/).map(e => `edge-${e}`)
+      : [];
+
+    const radiusClass = this.radius && RADIUS_PRESETS.has(this.radius)
+      ? `radius-${this.radius}`
+      : '';
+
+    const customRadius = this.radius && !RADIUS_PRESETS.has(this.radius)
+      ? this.radius
+      : undefined;
+
+    const cls = [
+      'surface',
+      intentClass,
+      elevClass,
+      ...edgeClasses,
+      radiusClass,
+      this.interactive ? 'interactive' : '',
+      this.selected ? 'selected' : '',
+      this.inactive ? 'inactive' : '',
+    ].filter(Boolean).join(' ');
+
+    return (
+      <Host style={{ display: 'contents' }}>
+        <Tag
+          class={cls}
+          style={customRadius ? { borderRadius: customRadius } : undefined}
+        >
+          <slot />
+        </Tag>
+      </Host>
+    );
+  }
+}

package/src/wc/components/TabGroup/TabGroup.tsx

@@ -0,0 +1,188 @@
+import { Component, Prop, Event, EventEmitter, Element, Listen, Watch, h, Host } from '@stencil/core';
+import {
+  getSelectableTabs,
+  isTabDivider,
+  type TabItem,
+  type TabItemTab,
+} from './tab-item-utils';
+
+export type TabBackground = 'faint' | 'medium' | 'bold' | 'strong' | 'always-dark';
+
+@Component({
+  tag: 'ds-tab-group',
+  styleUrl: 'TabGroup.css',
+  scoped: true,
+})
+export class TabGroup {
+  @Element() el!: HTMLElement;
+
+  @Prop({ mutable: true }) value: string = '';
+  @Prop() tabs: TabItem[] = [];
+  @Prop() background: TabBackground | undefined;
+  @Prop({ attribute: 'aria-label' }) ariaLabel: string | undefined;
+  @Prop({ attribute: 'aria-labelledby' }) ariaLabelledby: string | undefined;
+  @Prop() orientation: 'horizontal' | 'vertical' = 'horizontal';
+
+  @Event() dsChange!: EventEmitter<string>;
+
+  private get selectableTabs(): TabItemTab[] {
+    return getSelectableTabs(this.tabs);
+  }
+
+  private selectTab(id: string, options?: { focus?: boolean }) {
+    this.value = id;
+    this.dsChange.emit(id);
+    if (options?.focus !== false) {
+      this.focusTab(id);
+    }
+  }
+
+  private focusTab(id: string) {
+    const btn = this.el.querySelector(`[data-tab-id="${id}"]`) as HTMLElement | null;
+    btn?.focus({ preventScroll: true });
+  }
+
+  /** Keep focus on the selected tab when value changes externally (e.g. BarNav menu). */
+  @Watch('value')
+  onValueChange(next: string, prev: string | undefined) {
+    if (prev === undefined || next === prev) return;
+
+    requestAnimationFrame(() => {
+      const active = document.activeElement as HTMLElement | null;
+      if (!active || !this.el.contains(active)) return;
+
+      const activeId = active.getAttribute('data-tab-id');
+      if (activeId === next) return;
+
+      const nextTab = this.el.querySelector(`[data-tab-id="${next}"]`) as HTMLElement | null;
+      if (nextTab) {
+        nextTab.focus({ preventScroll: true });
+      } else {
+        active.blur();
+      }
+    });
+  }
+
+  /**
+   * Find the next non-disabled tab index relative to `from`, stepping by `step`.
+   * Returns `from` unchanged if no other enabled tab exists.
+   */
+  private findEnabled(from: number, step: 1 | -1): number {
+    const tabs = this.selectableTabs;
+    const len = tabs.length;
+    for (let n = 0; n < len; n++) {
+      const i = (from + step * (n + 1) + len * (n + 1)) % len;
+      if (!tabs[i]?.disabled) return i;
+    }
+    return from;
+  }
+
+  @Listen('keydown')
+  handleKeyDown(e: KeyboardEvent) {
+    const tabs = this.selectableTabs;
+    if (!tabs.length) return;
+
+    const currentIdx = tabs.findIndex(t => t.id === this.value);
+    const isVertical = this.orientation === 'vertical';
+
+    let nextIdx: number | null = null;
+
+    if (!isVertical) {
+      if (e.key === 'ArrowRight') {
+        nextIdx = this.findEnabled(currentIdx, 1);
+      } else if (e.key === 'ArrowLeft') {
+        nextIdx = this.findEnabled(currentIdx, -1);
+      }
+    } else {
+      if (e.key === 'ArrowDown') {
+        nextIdx = this.findEnabled(currentIdx, 1);
+      } else if (e.key === 'ArrowUp') {
+        nextIdx = this.findEnabled(currentIdx, -1);
+      }
+    }
+
+    if (e.key === 'Home') {
+      const first = tabs.findIndex(t => !t.disabled);
+      nextIdx = first === -1 ? null : first;
+    } else if (e.key === 'End') {
+      const lastEnabled = [...tabs].reverse().findIndex(t => !t.disabled);
+      nextIdx = lastEnabled === -1 ? null : tabs.length - 1 - lastEnabled;
+    }
+
+    if (nextIdx !== null) {
+      e.preventDefault();
+      const next = tabs[nextIdx];
+      this.selectTab(next.id);
+    }
+  }
+
+  private getBgClass(): string {
+    if (!this.background || this.background === 'faint') return '';
+    if (this.background === 'always-dark') return 'on-always-dark';
+    return `on-${this.background}`;
+  }
+
+  render() {
+    const bgClass = this.getBgClass();
+    const isVertical = this.orientation === 'vertical';
+
+    return (
+      <Host class="tab-group-host">
+        <div
+          role="tablist"
+          class={{ 'tab-list': true, 'tab-list--vertical': isVertical }}
+          aria-label={this.ariaLabel}
+          aria-labelledby={this.ariaLabelledby}
+          aria-orientation={isVertical ? 'vertical' : undefined}
+        >
+          {this.tabs.map((tab, index) => {
+            if (isTabDivider(tab)) {
+              return (
+                <div
+                  key={`divider-${index}`}
+                  class={{
+                    'tab-divider': true,
+                    'tab-divider--vertical': isVertical,
+                  }}
+                  aria-hidden="true"
+                >
+                  <div class="tab-divider__line" />
+                </div>
+              );
+            }
+
+            const isSelected = tab.id === this.value;
+            return (
+              <button
+                key={tab.id}
+                type="button"
+                role="tab"
+                data-tab-id={tab.id}
+                class={{
+                  tab: true,
+                  'tab--selected': isSelected,
+                  [bgClass]: !!bgClass,
+                }}
+                aria-selected={isSelected}
+                aria-disabled={tab.disabled || undefined}
+                aria-controls={tab.panelId ?? undefined}
+                disabled={tab.disabled}
+                tabIndex={isSelected ? 0 : -1}
+                onClick={() => !tab.disabled && this.selectTab(tab.id)}
+              >
+                <span class={{
+                  tab__label: true,
+                  'tab__label--dot': !!tab.dot,
+                  [isSelected ? 'text-body-small-emphasis' : 'text-body-small']: true,
+                }}>
+                  {tab.label}
+                  {tab.dot && <span class="tab__dot" aria-hidden="true" />}
+                </span>
+              </button>
+            );
+          })}
+        </div>
+      </Host>
+    );
+  }
+}

package/src/wc/components/TabGroup/tab-item-utils.ts

@@ -0,0 +1,24 @@
+export interface TabItemDivider {
+  type: 'divider';
+}
+
+export interface TabItemTab {
+  id: string;
+  label: string;
+  disabled?: boolean;
+  /** id of the tabpanel this tab controls */
+  panelId?: string;
+  /** Show a notification dot (brand) on the tab — no count, matching panel-nav. */
+  dot?: boolean;
+}
+
+export type TabItem = TabItemTab | TabItemDivider;
+
+export function isTabDivider(item: TabItem): item is TabItemDivider {
+  return 'type' in item && item.type === 'divider';
+}
+
+/** Tab entries that participate in selection, keyboard nav, and URL matching. */
+export function getSelectableTabs(tabs: TabItem[]): TabItemTab[] {
+  return tabs.filter((t): t is TabItemTab => !isTabDivider(t));
+}