create-wakii-stack 0.0.0-stage → 0.1.0

package/stack-template/app/ui-kit/src/ui/select/index.tsx

@@ -0,0 +1,302 @@
+// Select — PrimeReact Dropdown/MultiSelect level (Tier 4+ nâng cấp):
+// filterable · multiple (chips + select-all) · option groups · loading · showClear
+// · editable · keyboard đầy đủ · ARIA listbox/combobox chuẩn WAI-ARIA.
+// GIỮ NGUYÊN: ariaLabel contract + a11y hơn antd (button+listbox thay span+click).
+// Depth contract 2026-10-19: trigger rest bg-s3 + ele-1 → hover nhấc ele-2 + viền
+// đậm ink/20; panel nổi = shadow-pop + ele-3 + wash; option hover tint accent/5;
+// stagger option mount 30ms (cap 12); empty icon float; mọi transition ease-smooth.
+import { useId, useMemo, useRef, useState, type KeyboardEvent } from 'react';
+import { Icon } from '../icons/index.js';
+import { Spinner } from '../spinner/index';
+
+const SMOOTH = 'transition-[background-color,border-color,box-shadow,color] duration-200 ease-[var(--ease-smooth)]';
+
+export interface SelectOption {
+  label: string;
+  value: string;
+  disabled?: boolean;
+  /** Option group header — các option con thuộc group này. */
+  items?: SelectOption[];
+}
+
+export interface SelectProps {
+  ariaLabel: string;
+  value?: string | string[];
+  onChange?: (value: string | string[]) => void;
+  options: SelectOption[];
+  placeholder?: string;
+  disabled?: boolean;
+  /** Gõ để lọc option trong panel. */
+  filterable?: boolean;
+  /** Multi-select mode — chips + select-all/clear-all. */
+  multiple?: boolean;
+  /** Giới hạn số chips hiển thị (overflow → "+N"). */
+  maxSelectedCount?: number;
+  /** Loading spinner trong panel. */
+  loading?: boolean;
+  /** Nút × xoá giá trị. */
+  showClear?: boolean;
+  /** Cho gõ giá trị tự do (editable). */
+  editable?: boolean;
+  className?: string;
+}
+
+// Flatten option groups → danh sách phẳng cho keyboard/selection
+function flattenOptions(options: SelectOption[]): Array<{ label: string; value: string; disabled?: boolean; group?: string }> {
+  const result: Array<{ label: string; value: string; disabled?: boolean; group?: string }> = [];
+  for (const opt of options) {
+    if (opt.items) {
+      for (const sub of opt.items) result.push({ ...sub, group: opt.label });
+    } else {
+      result.push({ label: opt.label, value: opt.value, disabled: opt.disabled });
+    }
+  }
+  return result;
+}
+
+export function Select({
+  ariaLabel,
+  value,
+  onChange,
+  options,
+  placeholder = 'Chọn…',
+  disabled = false,
+  filterable = false,
+  multiple = false,
+  maxSelectedCount,
+  loading = false,
+  showClear = false,
+  editable = false,
+  className,
+}: SelectProps) {
+  const [open, setOpen] = useState(false);
+  const [active, setActive] = useState(0);
+  const [search, setSearch] = useState('');
+  const listId = useId();
+  const listRef = useRef<HTMLUListElement>(null);
+
+  const flat = useMemo(() => flattenOptions(options), [options]);
+  const filteredFlat = useMemo(() => {
+    if (!filterable || !search.trim()) return flat;
+    const q = search.toLowerCase();
+    return flat.filter((o) => o.label.toLowerCase().includes(q));
+  }, [flat, filterable, search]);
+
+  const selectedValues = multiple ? (Array.isArray(value) ? value : value ? [value] : []) : value ? [String(value)] : [];
+  const selectedLabels = selectedValues.map((v) => flat.find((o) => o.value === v)?.label ?? v);
+  const hasValue = selectedValues.length > 0;
+
+  function commit(value: string) {
+    if (multiple) {
+      const next = selectedValues.includes(value)
+        ? selectedValues.filter((v) => v !== value)
+        : [...selectedValues, value];
+      onChange?.(next);
+    } else {
+      onChange?.(value);
+      setOpen(false);
+    }
+  }
+
+  function onKeyDown(e: KeyboardEvent<HTMLButtonElement>) {
+    if (disabled) return;
+    switch (e.key) {
+      case 'Enter':
+      case ' ':
+        e.preventDefault();
+        if (!open) { setOpen(true); setActive(0); }
+        else if (!editable && filteredFlat[active] && !filteredFlat[active].disabled) commit(filteredFlat[active].value);
+        break;
+      case 'ArrowDown':
+        e.preventDefault();
+        if (!open) { setOpen(true); setActive(0); }
+        else setActive((i) => Math.min(filteredFlat.length - 1, i + 1));
+        break;
+      case 'ArrowUp':
+        e.preventDefault();
+        if (open) setActive((i) => Math.max(0, i - 1));
+        else { setOpen(true); setActive(filteredFlat.length - 1); }
+        break;
+      case 'Escape':
+        setOpen(false);
+        break;
+      case 'Home':
+        if (open) { e.preventDefault(); setActive(0); }
+        break;
+      case 'End':
+        if (open) { e.preventDefault(); setActive(filteredFlat.length - 1); }
+        break;
+    }
+  }
+
+  function clearValue(e: React.MouseEvent) {
+    e.stopPropagation();
+    onChange?.(multiple ? [] : '');
+    setSearch('');
+  }
+
+  // Chips hiển thị (multiple)
+  const visibleChips = maxSelectedCount ? selectedLabels.slice(0, maxSelectedCount) : selectedLabels;
+  const overflowCount = selectedLabels.length - visibleChips.length;
+
+  return (
+    <span className={`relative inline-flex w-full${className ? ` ${className}` : ''}`}>
+      <button
+        type="button"
+        role="combobox"
+        aria-label={ariaLabel}
+        aria-haspopup="listbox"
+        aria-expanded={open}
+        aria-controls={open ? listId : undefined}
+        disabled={disabled}
+        onClick={() => (disabled ? undefined : setOpen((o) => !o))}
+        onKeyDown={(e) => { if (!editable) onKeyDown(e); }}
+        className={`inline-flex h-8 w-full min-w-[120px] cursor-pointer items-center justify-between gap-1 rounded-lg border bg-s3 px-3 text-body shadow-[var(--ele-1)] ${SMOOTH} hover:shadow-[var(--ele-2)] focus-visible:outline-none focus-visible:ring-[3px] focus-visible:ring-accent/40 ${
+          open ? 'border-accent-hi' : 'border-line hover:border-ink/20'
+        } ${disabled ? 'cursor-not-allowed bg-ink/5 text-ink4 shadow-none' : 'text-ink'}`}
+      >
+        <span className="min-w-0 truncate">
+          {multiple && visibleChips.length > 0 ? (
+            <span className="flex flex-wrap items-center gap-1">
+              {visibleChips.map((label, i) => (
+                <span key={i} className="inline-flex items-center gap-0.5 rounded-1 border border-line bg-s3 px-1.5 py-0.5 text-meta text-ink2">
+                  {label}
+                </span>
+              ))}
+              {overflowCount > 0 && <span className="text-meta text-ink3">+{overflowCount}</span>}
+            </span>
+          ) : hasValue && !multiple ? (
+            selectedLabels[0] ?? ''
+          ) : (
+            <span className="text-ink4">{placeholder}</span>
+          )}
+        </span>
+        <span className="flex shrink-0 items-center gap-0.5">
+          {showClear && hasValue && !disabled && (
+            <span
+              role="button"
+              aria-label="Xoá"
+              tabIndex={0}
+              onClick={(e) => { e.stopPropagation(); clearValue(e as unknown as React.MouseEvent); }}
+              onKeyDown={(e) => {
+                // span-role-button phải Operable bằng keyboard (Enter/Space) — axe
+                if (e.key === 'Enter' || e.key === ' ') {
+                  e.preventDefault();
+                  e.stopPropagation();
+                  clearValue(e as unknown as React.MouseEvent);
+                }
+              }}
+              className="cursor-pointer text-ink3 hover:text-ink"
+            >
+              ×
+            </span>
+          )}
+          <span aria-hidden="true" className={`text-ink3 transition-transform duration-200 ease-[var(--ease-smooth)] ${open ? 'rotate-180' : ''}`}>▾</span>
+        </span>
+      </button>
+
+      {open && (
+        <span className="absolute left-0 top-full mt-1 z-[var(--z-popover)] block w-full min-w-[160px]">
+          <span className="block origin-top overflow-hidden rounded-xl border border-line bg-s2 bg-[image:var(--wash)] shadow-[var(--shadow-pop),var(--ele-3)] animate-[bp-zoom-in_var(--motion-fast)_var(--ease-enter)]">
+            {/* Filter input */}
+            {filterable && (
+              <span className="block border-b border-line2 p-2">
+                <input
+                  autoFocus
+                  aria-label={`${ariaLabel} — tìm kiếm`}
+                  value={search}
+                  onChange={(e) => { setSearch(e.target.value); setActive(0); }}
+                  onKeyDown={(e) => {
+                    if (e.key === 'ArrowDown') { e.preventDefault(); setActive((i) => Math.min(filteredFlat.length - 1, i + 1)); }
+                    if (e.key === 'ArrowUp') { e.preventDefault(); setActive((i) => Math.max(0, i - 1)); }
+                    if (e.key === 'Enter' && filteredFlat[active]) { e.stopPropagation(); commit(filteredFlat[active].value); setOpen(false); }
+                    if (e.key === 'Escape') setOpen(false);
+                  }}
+                  placeholder="Tìm kiếm…"
+                  className="h-7 w-full rounded-1 border border-line bg-s2 px-2 text-label text-ink placeholder:text-ink4 focus:border-accent-hi focus:outline-none"
+                />
+              </span>
+            )}
+
+            {/* Select all / clear all (multiple) */}
+            {multiple && filteredFlat.length > 0 && (
+              <span className="flex items-center justify-between border-b border-line2 px-3 py-1">
+                <button
+                  type="button"
+                  className="cursor-pointer border-none bg-transparent text-[10px] text-accent hover:underline"
+                  onClick={() => onChange?.(filteredFlat.map((o) => o.value))}
+                >
+                  Chọn tất cả
+                </button>
+                <button
+                  type="button"
+                  className="cursor-pointer border-none bg-transparent text-[10px] text-ink3 hover:underline"
+                  onClick={() => onChange?.([])}
+                >
+                  Bỏ tất cả
+                </button>
+              </span>
+            )}
+
+            {/* Loading */}
+            {loading ? (
+              <span className="block p-3 text-center text-body text-ink3">
+                <Spinner label="Đang tải options" variant="dots" />
+              </span>
+            ) : filteredFlat.length === 0 ? (
+              <span className="flex items-center justify-center gap-2 p-3 text-center text-body text-ink3">
+                {/* Empty icon float 3s (depth contract — empty-state icon float) */}
+                <Icon name="search" size={14} aria-hidden className="animate-[bp-float_3s_var(--ease-smooth)_infinite]" />
+                Không có kết quả
+              </span>
+            ) : (
+              <ul ref={listRef} id={listId} role="listbox" aria-label={ariaLabel}
+                className="m-0 max-h-60 min-h-[104px] list-none overflow-auto p-1">
+                {filteredFlat.map((option, i) => {
+                  const isSelected = selectedValues.includes(option.value);
+                  const isActive = i === active;
+                  const showGroup = i > 0 && filteredFlat[i - 1].group !== option.group;
+                  return (
+                    <li key={option.value}>
+                      {option.group && showGroup && (
+                        <div className="px-3 pt-2 text-[10px] font-semibold uppercase tracking-[0.04em] text-ink3">
+                          {option.group}
+                        </div>
+                      )}
+                      <div
+                        role="option"
+                        aria-selected={isSelected}
+                        aria-disabled={option.disabled || undefined}
+                        onMouseEnter={() => setActive(i)}
+                        onClick={() => !option.disabled && commit(option.value)}
+                        // Stagger mount 30ms/option (cap 12 mục — list dài không trễ quá ~360ms)
+                        style={{ animationDelay: `${Math.min(i, 12) * 30}ms` }}
+                        className={`flex h-8 cursor-pointer items-center rounded-lg px-3 text-body animate-[bp-slide-up-in_240ms_var(--ease-smooth)_backwards] ${SMOOTH} ${
+                          isSelected ? 'bg-accent/10 font-semibold text-accent' : 'text-ink hover:bg-accent/5'
+                        } ${isActive ? 'outline-1 -outline-offset-1 outline-accent/40' : ''} ${option.disabled ? 'cursor-not-allowed text-ink3' : ''}`}
+                      >
+                        {multiple && (
+                          <span className={`mr-2 size-3.5 shrink-0 rounded-[4px] border ${isSelected ? 'border-accent bg-accent' : 'border-line bg-s2'}`}>
+                            {isSelected && <span className="grid size-full place-items-center"><Icon name="check" size={10} className="text-white" /></span>}
+                          </span>
+                        )}
+                        {/* label chiếm phần còn — check icon selected bám mép phải (single; multiple có checkbox riêng) */}
+                        <span className="min-w-0 flex-1 truncate">{option.label}</span>
+                        {!multiple && isSelected && (
+                          <Icon name="check" size={12} className="shrink-0 text-accent" />
+                        )}
+                      </div>
+                    </li>
+                  );
+                })}
+                {filteredFlat.length === 0 && filterable && (
+                  <li className="p-3 text-center text-body text-ink3">Không có kết quả</li>
+                )}
+              </ul>
+            )}
+          </span>
+        </span>
+      )}
+    </span>
+  );
+}

package/stack-template/app/ui-kit/src/ui/select/select.stories.tsx

@@ -0,0 +1,268 @@
+// Select stories — states: selected/placeholder/disabled.
+// Parity matrix antd→tokens: docs/parity-matrix.md
+import { useState } from 'react';
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { Checkbox } from '../checkbox/index';
+import { RadioGroup } from '../radio/index';
+import { Select } from './index';
+
+const meta = {
+  title: 'Forms/Select',
+  component: Select,
+  tags: ['autodocs'],
+} satisfies Meta<typeof Select>;
+export default meta;
+type S = StoryObj<typeof meta>;
+
+type Story = StoryObj<typeof meta>;
+
+const OPTIONS = [
+  { label: 'Cần làm', value: 'todo' },
+  { label: 'Đang làm', value: 'in_progress' },
+  { label: 'Xong', value: 'done' },
+];
+
+function OursSelected() {
+  const [value, setValue] = useState<string>('todo');
+  return <Select ariaLabel="Parity select — selected" options={OPTIONS} value={value} onChange={(v) => setValue(String(v))} />;
+}
+
+export const Selected: Story = {
+  args: { ariaLabel: 'S', options: OPTIONS, value: 'todo' },
+  render: () => <OursSelected />,
+};
+export const Placeholder: Story = {
+  args: { ariaLabel: 'Parity select — placeholder', options: OPTIONS, placeholder: 'Chọn trạng thái…' },
+};
+
+// ── Coverage audit additions (antd Select parity) — EN demos ────────────────────
+
+const TASK_OPTIONS = [
+  { label: 'Learn TypeScript', value: 'ts' },
+  { label: 'Learn Rust', value: 'rust' },
+  { label: 'Write E2E tests', value: 'e2e' },
+  { label: 'Fix nginx gateway', value: 'gateway' },
+  { label: 'Saga compensation demo', value: 'saga' },
+  { label: 'Seed demo users', value: 'seed' },
+];
+
+/** Filterable — type in the panel to narrow options (antd showSearch). */
+export const Filterable: Story = {
+  name: 'Filterable — type to search options',
+  args: { ariaLabel: 'Filterable select', options: TASK_OPTIONS, filterable: true, placeholder: 'Pick a task…' },
+};
+
+/** Multiple — chips + select-all/clear-all inside the panel (antd mode="multiple"). */
+export const Multiple: Story = {
+  name: 'Multiple — chips + select all',
+  args: { ariaLabel: 'Multiple select', options: OPTIONS },
+  render: () => <SelectMultipleDemo />,
+};
+
+/** MaxSelectedCount — chips overflow folds into "+N" (antd maxTagCount). */
+export const MaxSelectedCount: Story = {
+  name: 'MaxSelectedCount — overflow becomes +N',
+  args: { ariaLabel: 'Capped multiple select', options: OPTIONS },
+  render: () => <SelectMaxSelectedDemo />,
+};
+
+/** OptionGroups — grouped headers inside the panel (antd options with options). */
+export const OptionGroups: Story = {
+  name: 'Option groups — grouped panel',
+  args: {
+    ariaLabel: 'Grouped select',
+    placeholder: 'Pick a service…',
+    options: [
+      {
+        label: 'Frontend',
+        value: 'group-fe',
+        items: [
+          { label: 'Shell (host)', value: 'shell' },
+          { label: 'Tasks remote', value: 'tasks' },
+        ],
+      },
+      {
+        label: 'Backend',
+        value: 'group-be',
+        items: [
+          { label: 'node-svc', value: 'node' },
+          { label: 'go-svc', value: 'go' },
+        ],
+      },
+    ],
+  },
+};
+
+/** Disabled — trigger locked, no panel. */
+export const Disabled: Story = {
+  args: { ariaLabel: 'Parity select — disabled', options: OPTIONS, value: 'todo', disabled: true },
+};
+
+/** Loading — spinner replaces the option list (antd loading). */
+export const Loading: Story = {
+  name: 'Loading — spinner in panel',
+  args: { ariaLabel: 'Loading select', options: TASK_OPTIONS, loading: true },
+};
+
+/** ShowClear — × next to the chevron clears the value (antd allowClear). */
+export const ShowClear: Story = {
+  name: 'ShowClear — × clears the value',
+  args: { ariaLabel: 'Clearable select', options: OPTIONS },
+  render: () => <SelectShowClearDemo />,
+};
+
+/** Editable — trigger stays typable while the panel is open (free value). */
+export const Editable: Story = {
+  name: 'Editable — free-text value',
+  args: { ariaLabel: 'Editable select', options: TASK_OPTIONS, editable: true, placeholder: 'Pick or type…' },
+};
+
+/** OptionDisabled — one locked option (antd disabled option). */
+export const OptionDisabled: Story = {
+  name: 'Option disabled — one locked option',
+  args: {
+    ariaLabel: 'Select with disabled option',
+    options: [
+      { label: 'Available plan', value: 'free' },
+      { label: 'Legacy plan', value: 'legacy', disabled: true },
+      { label: 'Enterprise plan', value: 'ent' },
+    ],
+    placeholder: 'Pick a plan…',
+  },
+};
+
+/** DarkTheme — trigger + open panel on dark canvas. */
+export const DarkTheme: Story = {
+  name: 'DarkTheme — trigger + panel on dark canvas',
+  args: { ariaLabel: 'Dark select', options: OPTIONS },
+  render: () => (
+    <div data-bp-theme="dark" className="w-72 rounded-xl bg-canvas p-4">
+      <Select ariaLabel="Dark select" options={OPTIONS} value="in_progress" />
+    </div>
+  ),
+};
+
+function SelectMultipleDemo() {
+  const [values, setValues] = useState<string[]>(['todo']);
+  return (
+    <div className="grid max-w-[320px] gap-3">
+      <Select ariaLabel="Multiple select" options={OPTIONS} multiple value={values} onChange={(v) => setValues(Array.isArray(v) ? v : [v])} placeholder="Pick statuses…" />
+      <p className="m-0 font-mono text-meta text-ink3">values: <strong className="text-ink">{JSON.stringify(values)}</strong></p>
+    </div>
+  );
+}
+
+function SelectMaxSelectedDemo() {
+  const [values, setValues] = useState<string[]>(['todo', 'in_progress', 'done']);
+  return (
+    <div className="grid max-w-[320px] gap-3">
+      <Select ariaLabel="Capped multiple select" options={OPTIONS} multiple maxSelectedCount={2} value={values} onChange={(v) => setValues(Array.isArray(v) ? v : [v])} placeholder="Pick statuses…" />
+      <p className="m-0 font-mono text-meta text-ink3">3 selected, max 2 chips → "+1"</p>
+    </div>
+  );
+}
+
+function SelectShowClearDemo() {
+  const [value, setValue] = useState<string>('todo');
+  return (
+    <div className="grid max-w-[320px] gap-3">
+      <Select ariaLabel="Clearable select" options={OPTIONS} showClear value={value} onChange={(v) => setValue(String(v))} placeholder="Pick a status…" />
+      <p className="m-0 font-mono text-meta text-ink3">value: <strong className="text-ink">{value || '—'}</strong></p>
+    </div>
+  );
+}
+
+/* ── Real-world cases (mission #13 — real-world stories sweep) ── */
+
+const CATALOG = [
+  { name: 'Trail Runner Pro', category: 'Shoes', brand: 'Nimbus', price: 129 },
+  { name: 'Field Watch 38', category: 'Accessories', brand: 'Krono', price: 249 },
+  { name: 'Studio Headphones', category: 'Audio', brand: 'Nimbus', price: 199 },
+  { name: 'City Backpack 22L', category: 'Bags', brand: 'Carryon', price: 89 },
+  { name: 'Desk Lamp Arc', category: 'Home', brand: 'Lumo', price: 59 },
+  { name: 'Running Tee Dry', category: 'Shoes', brand: 'Carryon', price: 35 },
+];
+const CATEGORIES = ['Shoes', 'Accessories', 'Audio', 'Bags', 'Home'];
+const BRANDS = ['Nimbus', 'Krono', 'Carryon', 'Lumo'];
+
+// Local wrapper — product filter: category + sort + brand checkboxes → live result count.
+function FilterBarInner() {
+  const [category, setCategory] = useState<string | undefined>(undefined);
+  const [sort, setSort] = useState('price-asc');
+  const [brands, setBrands] = useState<string[]>([]);
+
+  const filtered = CATALOG.filter(
+    (p) => (!category || p.category === category) && (brands.length === 0 || brands.includes(p.brand)),
+  );
+  const sorted = [...filtered].sort((a, b) =>
+    sort === 'price-asc' ? a.price - b.price : sort === 'price-desc' ? b.price - a.price : a.name.localeCompare(b.name),
+  );
+
+  return (
+    <div className="flex w-full max-w-2xl flex-col gap-4">
+      <div className="flex flex-wrap items-end gap-4">
+        <div className="flex flex-col gap-1">
+          <span className="text-label text-ink2">Category</span>
+          <Select
+            ariaLabel="Category"
+            placeholder="All categories"
+            value={category}
+            onChange={(v) => setCategory(typeof v === 'string' ? v : undefined)}
+            options={CATEGORIES.map((c) => ({ label: c, value: c }))}
+            className="w-44"
+          />
+        </div>
+        <div className="flex flex-col gap-1">
+          <span className="text-label text-ink2">Sort by</span>
+          <RadioGroup
+            aria-label="Sort by"
+            value={sort}
+            onChange={setSort}
+            options={[
+              { label: 'Price ↑', value: 'price-asc' },
+              { label: 'Price ↓', value: 'price-desc' },
+              { label: 'Name', value: 'name' },
+            ]}
+          />
+        </div>
+        <div className="flex flex-col gap-1">
+          <span className="text-label text-ink2">Brand</span>
+          <div className="flex flex-wrap gap-3">
+            {BRANDS.map((brand) => (
+              <Checkbox
+                key={brand}
+                checked={brands.includes(brand)}
+                onChange={(checked) => setBrands((prev) => (checked ? [...prev, brand] : prev.filter((b) => b !== brand)))}
+              >
+                {brand}
+              </Checkbox>
+            ))}
+          </div>
+        </div>
+      </div>
+
+      <div className="rounded-lg border border-line bg-s1 p-3">
+        <span className="text-label text-ink2">
+          {sorted.length} of {CATALOG.length} products
+        </span>
+        <ul className="m-0 mt-2 flex list-none flex-col gap-1 p-0">
+          {sorted.map((p) => (
+            <li key={p.name} className="flex items-center justify-between text-body text-ink">
+              <span>
+                {p.name} <span className="text-ink3">· {p.brand}</span>
+              </span>
+              <span className="text-ink2">${p.price}</span>
+            </li>
+          ))}
+        </ul>
+      </div>
+    </div>
+  );
+}
+
+export const FilterBar: S = {
+  name: 'FilterBar — product filters: category + sort + brands, live results',
+  // args = props bắt buộc của Select (meta component) — renderdemo tự render wrapper
+  args: { ariaLabel: 'Category', options: [] },
+  render: () => <FilterBarInner />,
+};