@wpic/ui 0.3.16 → 0.5.0

package/CHANGELOG.md

@@ -0,0 +1,34 @@
+# Changelog
+
+## 0.5.0 — 2026-09-08
+
+- Add opt-in `WThemeProvider`, UI5 light/dark tokens, typed color overrides, `themeVariables`, and chart palettes. Existing consumers keep their default appearance.
+- Add `WPageHeader` with actions, metadata and unframed filters.
+- Apply the validated controls, monochrome primary/neutral secondary buttons, subtle cards and white-thumb switches inside the provider.
+- Carry themes into all shared popovers, including calendars, date ranges and editable tags. Add nested Escape handling and safe outside-listener cleanup.
+- Make date clear actions keyboard accessible; preserve date bounds, emitted values and legacy props. Fix local date serialization in date-range calendars.
+- Ensure packaged CSS always includes the public token declarations, even when compiled utilities already reference their names.
+- Add packaged-browser regression coverage for light/dark scopes, customization, nested panels, switches, dates and backwards-compatible semantic components.
+
+
+## 0.4.0 — 2026-09-08
+
+### Banners, tags and badges
+
+- Shared Tailwind palettes reproduce the approved Analyze light/dark laboratory: blue information, yellow attention, emerald success and rose error.
+- `WBanner` adds title, lead, actions slot, optional dismissal and an explicit theme override while retaining slot-only usage.
+- `WTag` adds controlled checkable tags, configurable selected color, normal/muted unselected appearance and a true disabled state. The selection indicator is a 14px circle with the approved larger check. Borders use 5% opacity.
+- `WBadge` uses stronger light fills, semibold light labels and the approved bottom padding. Adds a compact `count` option and explicit theme selection.
+- `theme="auto"` follows `.dark`; explicit `light`/`dark` values support previews without inheriting the host theme.
+- Editable and removable tags remain supported; combined interactions no longer create nested buttons. `WAlert` now delegates to `WBanner` and retains its props, slot and close event.
+- Published documentation defines when to use each component. Browser coverage checks distributed CSS without host Tailwind, themes, selection, keyboard interaction, disabled controls, popover editing, removal and dismissal.
+
+### Adoption notes
+
+This minor release intentionally updates appearance. The default tag and badge label size is now `text-xs`; badges use slightly more bottom padding. `WBadge.bordered` remains opt-in for compatibility (enable it for the laboratory treatment). Existing `WTag` variants, editable string model, remove event and compact size remain available. `primary` badges retain their inverted neutral appearance. Muted tags are selectable, not disabled.
+
+Import `@wpic/ui/style.css` alongside the components. No host Tailwind source scanning is required. See `COMPONENTS.md` for examples and API details.
+
+### Verification
+
+Run `npm run build` followed by `npm run test:semantic`. The browser tests use Google Chrome (`npx playwright install chrome` if needed). Open `/test-ui/semantic.html` with `npm run test:ui` for the standalone package showcase.

package/COMPONENTS.md

@@ -0,0 +1,680 @@
+# COMPONENTS.md — wpic-ui component reference
+Use this as reference when writing Vue components. Updated for 0.5.0.
+
+
+## Theme provider and customization (0.5)
+
+The UI5 preset is **opt-in**. Existing consumers without `WThemeProvider` keep their current styling and existing component props/events. Import the packaged stylesheet; no host Tailwind scanning is required.
+
+```vue
+<script setup lang="ts">
+import { WThemeProvider, WButton, type WThemeOverrides } from '@wpic/ui'
+import '@wpic/ui/style.css'
+const colors: WThemeOverrides = {
+  light: { accent: '#85C531', primary: '#171717', onPrimary: '#FFFFFF' },
+  dark: { surface: '#151515', popover: '#1F201D', raised: '#2A2A28', primary: '#FFFFFF', onPrimary: '#171717' },
+}
+</script>
+<template>
+  <WThemeProvider mode="auto" :colors="colors">
+    <WButton>Save</WButton>
+  </WThemeProvider>
+</template>
+```
+
+`mode` accepts `auto` (inherits a parent provider or the document `.dark` class), `light`, or `dark`. `preset` currently accepts `ui5`. `colors` is a partial map per mode; unspecified entries use the preset. A nested provider can preview another theme without changing the document or saved application preference.
+
+Color keys (`WThemeColors`): `canvas`, `surface`, `input`, `raised`, `popover`, `border`, `borderHover`, `text`, `muted`, `dim`, `accent`, `onAccent`, `primary`, `primaryHover`, `onPrimary`, `secondary`, `secondaryHover`, `onSecondary`, `secondaryShadow`, `switchOn`, `switchOff`, `switchDisabled`, `switchThumb`, `focusRing`, `positive`, `negative`. Secondary and switch backgrounds accept CSS gradients. `focusRing` defaults to the accent at 18% opacity. Change both foreground and background when customizing contrast.
+
+The provider supplies prefixed CSS variables and the existing surface/text aliases. `--wpic-primary` remains an accent alias for legacy components; monochrome action buttons use `--wpic-button-primary`. `themeVariables(mode, overrides)` exposes the same mapping for document-level integration. Use the provider's **colors prop** for scoped overrides that must follow teleports. Direct DOM CSS overrides are not copied to teleported panels.
+
+`WPopover`, date calendars, ranges, month pickers, selects and editable-tag option panels receive the provider context directly. Panels inherit the selected palette even outside the provider's DOM subtree. Nested popovers keep their parent open when selecting a child option; Escape closes the innermost visible panel and returns focus to its anchor.
+
+UI5 uses 36px default controls (explicit small/large sizes and plain selects retain their sizing), standard button radii, subtle card contours, uniform input fills, and a 1px accent focus border plus a 3px translucent ring. Disabled and validation states remain distinct. `WTable` structure and behavior are unchanged.
+
+### WPageHeader
+
+Props: `title: string`, `description?: string`, `headingLevel?: 1 | 2` (default 1). Slots: `actions`, `metadata`, `filters`. Titles wrap, actions can move to the next line, filters have no border or internal padding. The consumer supplies outer page spacing. Existing application headers can forward their slots through this component.
+
+### Chart palettes
+
+`chartPalettes.light` and `.dark` contain six stable series colors: blue, teal, violet, amber, rose, slate. WPIC green is reserved for UI accents. Choose by theme and keep series-to-color assignments stable; retain labels/legends when displaying multiple series. Consumers can supply their own palette arrays.
+
+### Date and switch additions
+
+- `WDatePicker`: a selected, clearable date shows one trailing clear button instead of a chevron. `clearLabel` localizes its accessible name (default `Clear date`). Clear emits the existing empty-string model/change values and closes the panel. Date bounds and output format remain unchanged.
+- `WDateRangePicker`: retains `DateRange | null`, presets and custom ranges; adds `disabled`, `ariaLabel`, and `clearLabel` (default `Clear date range`). Clear emits `null`. Calendar dates use local year/month/day, avoiding UTC day shifts in positive time zones.
+- `WToggle`: retains boolean v-model, default label slot and `disabled`; adds `ariaLabel`. The actual button has `role="switch"` and `aria-checked`. The UI5 disabled track is dark in dark mode, with a white thumb.
+
+## Banners, tags and badges: usage
+
+| Component | Purpose | Examples |
+|---|---|---|
+| `WBanner` | Explain a contextual message, optionally with an action | Import failed; data updated |
+| `WTag` | Categorize an item or select a category filter | Tmall, Japan, Advertising |
+| `WBadge` | Indicate a read-only status or count | Completed, Needs review, 3 |
+
+Tags use neutral or blue categories by default. Checkable tags may use a configurable selection color; that color indicates selection, not severity. `uncheckedAppearance="muted"` only changes appearance: the tag remains clickable and keyboard accessible. Use `disabled` to actually prevent interaction. Several tags may describe the same item.
+
+Badges use neutral for no severity, blue for information, yellow for attention, emerald for success and rose for error. Keep a visible label or accessible count context; color alone is insufficient. Status badges belong next to the item they describe. They are not buttons.
+
+All three components accept `theme="auto"` (default, follows an ancestor `.dark`), `theme="light"` or `theme="dark"`. Explicit themes stay independent of the application theme, including a light preview within a dark page. Import `@wpic/ui/style.css`; the package contains the required Tailwind utilities, so host source scanning is unnecessary.
+
+```vue
+<WBanner variant="warning" title="Attention needed" lead="Review this before continuing."
+  dismissible @close="showBanner = false" v-if="showBanner">
+  Check the source data before publishing.
+  <template #actions><WButton @click="review">Review data</WButton></template>
+</WBanner>
+<WTag variant="info">Advertising</WTag>
+<WTag checkable v-model:checked="selected" checked-variant="success" unchecked-appearance="muted">Tmall</WTag>
+<WBadge variant="success" :icon="CircleCheck" bordered>Completed</WBadge>
+<WBadge variant="warning" count bordered aria-label="3 reports need review">3</WBadge>
+```
+
+`WBanner` emits `close`; the parent owns dismissal and restoration. `WAlert` is retained as a compatibility wrapper around `WBanner`. Prefer `WBanner` for new contextual messages.
+
+## WAlert
+
+**Import:** `import { WAlert } from '@wpic/ui'`
+
+**Props:**
+```ts
+variant?: 'info' | 'success' | 'warning' | 'error'
+title?: string
+dismissible?: boolean
+```
+
+**Emits:**
+```ts
+close: []
+```
+
+---
+
+## WAvatar
+
+**Import:** `import { WAvatar } from '@wpic/ui'`
+
+**Props:**
+```ts
+name: string
+src?: string
+size?: 'sm' | 'md' | 'lg'
+```
+
+---
+
+## WBadge
+
+**Import:** `import { WBadge } from '@wpic/ui'`
+
+```ts
+variant?: 'default' | 'neutral' | 'primary' | 'success' | 'warning' | 'error' | 'info'
+size?: 'sm' | 'md' // default md; sm retains the compact 10px label
+icon?: Component
+dot?: boolean
+bordered?: boolean // default false, preserving existing callers
+count?: boolean // centered compact counter
+theme?: 'auto' | 'light' | 'dark'
+```
+
+Light badges have stronger fills and semibold labels. Default badges use `text-xs`, top padding `0.125rem` and bottom padding `2.5px`. `primary` retains its inverted neutral treatment.
+
+---
+
+## WBanner
+
+**Import:** `import { WBanner } from '@wpic/ui'`
+
+```ts
+variant?: 'info' | 'warning' | 'error' | 'success' // default info
+icon?: Component
+title?: string
+lead?: string
+dismissible?: boolean // default false
+dismissLabel?: string // default "Dismiss"; localize in the caller
+theme?: 'auto' | 'light' | 'dark'
+```
+
+Slots: default (body or standalone message), `actions`. Emits `close`. Warnings and errors use `role="alert"`; information and success use `role="status"`. Existing slot-only content is supported.
+
+---
+
+## WButton
+
+**Import:** `import { WButton } from '@wpic/ui'`
+
+**Props:**
+```ts
+variant?: 'primary' | 'secondary' | 'destructive' | 'ghost' | 'outline'
+size?: 'xs' | 'sm' | 'md' | 'lg'
+loading?: boolean
+disabled?: boolean
+icon?: object | Function
+href?: string
+```
+
+**Emits:**
+```ts
+click: [e: MouseEvent]
+```
+
+---
+
+## WCard
+
+**Import:** `import { WCard } from '@wpic/ui'`
+
+**Props:**
+```ts
+title?: string
+empty?: boolean
+noPadding?: boolean
+bodyClass?: string
+borderless?: boolean
+headerDivider?: boolean // defaults to true
+padding?: 'sm' | 'md' | 'lg' // shared header/body/footer spacing; defaults to md
+```
+
+---
+
+## WCheckbox
+
+**Import:** `import { WCheckbox } from '@wpic/ui'`
+
+**Props:**
+```ts
+disabled?: boolean
+```
+
+---
+
+## WEmptyState
+
+**Import:** `import { WEmptyState } from '@wpic/ui'`
+
+**Props:**
+```ts
+icon?: Component
+title: string
+description?: string
+```
+
+---
+
+## WFileList
+
+**Import:** `import { WFileList } from '@wpic/ui'`
+
+**Props:**
+```ts
+files: any[]
+nameKey?: string
+idKey?: string
+statusKey?: string
+selectedId?: number | string | null
+removable?: boolean
+```
+
+**Emits:**
+```ts
+select: [item: any]
+remove: [item: any]
+```
+
+---
+
+## WFilter
+
+**Import:** `import { WFilter } from '@wpic/ui'`
+
+**Emits:**
+```ts
+'update:modelValue': [value: T]
+```
+
+---
+
+## WFormLabel
+
+**Import:** `import { WFormLabel } from '@wpic/ui'`
+
+**Props:**
+```ts
+required?: boolean
+```
+
+---
+
+## WImageTile
+
+**Import:** `import { WImageTile } from '@wpic/ui'`
+
+**Props:**
+```ts
+src: string
+selected?: boolean
+alt?: string
+```
+
+**Emits:**
+```ts
+click: []
+```
+
+---
+
+## WInput
+
+**Import:** `import { WInput } from '@wpic/ui'`
+
+**Props:**
+```ts
+icon?: object | Function
+label?: string
+placeholder?: string
+required?: boolean
+type?: string
+disabled?: boolean
+size?: 'sm' | 'md' | 'lg'
+clearable?: boolean
+```
+
+---
+
+## WModal
+
+**Import:** `import { WModal } from '@wpic/ui'`
+
+**Props:**
+```ts
+title?: string
+subtitle?: string
+size?: 'sm' | 'md' | 'lg' | 'xl' | '2xl' | 'full'
+zIndex?: string
+hideClose?: boolean
+noPadding?: boolean
+```
+
+**Emits:**
+```ts
+close: []
+```
+
+---
+
+## WOptionPopover
+
+**Import:** `import { WOptionPopover } from '@wpic/ui'`
+
+**Props:**
+```ts
+modelValue: string | null
+options: PopoverOption[]
+anchor: HTMLElement | null
+```
+
+**Emits:**
+```ts
+'update:modelValue': [value: string]
+'close': []
+```
+
+---
+
+## WPagination
+
+**Import:** `import { WPagination } from '@wpic/ui'`
+
+**Props:**
+```ts
+modelValue: number
+total: number
+limit?: number
+syncUrl?: boolean       // default: true; automatically false inside WModal
+queryParam?: string     // default: 'page'
+```
+
+**Emits:**
+```ts
+'update:modelValue': [p: number]
+```
+
+---
+
+## WPillGroup
+
+**Import:** `import { WPillGroup } from '@wpic/ui'`
+
+**Props:**
+```ts
+options: Option[]
+multiple?: boolean
+size?: 'sm' | 'md'
+disabled?: boolean
+```
+
+---
+
+## WPopover
+
+**Import:** `import { WPopover } from '@wpic/ui'`
+
+**Props:**
+```ts
+open: boolean
+anchor: HTMLElement | null
+placement?: 'top' | 'bottom' | 'left' | 'right' | 'bottom-start' | 'bottom-end' | 'top-start' | 'top-end'
+width?: string
+minWidth?: string
+maxHeight?: string
+offset?: number
+```
+
+**Emits:**
+```ts
+close: []
+```
+
+---
+
+## WProgress
+
+**Import:** `import { WProgress } from '@wpic/ui'`
+
+**Props:**
+```ts
+value: number
+max?: number
+color?: string
+size?: 'sm' | 'md' | 'lg'
+label?: string
+animated?: boolean
+```
+
+---
+
+## WSearchSelect
+
+**Import:** `import { WSearchSelect } from '@wpic/ui'`
+
+**Props:**
+```ts
+modelValue?: string | number | (string | number)[]
+options?: Option[]
+placeholder?: string
+size?: 'sm' | 'md' | 'lg'
+multiple?: boolean
+maxLabels?: number
+pinnedOptions?: Option[]
+```
+
+**Emits:**
+```ts
+'update:modelValue': [v: any]
+```
+
+---
+
+## WSelect
+
+**Import:** `import { WSelect } from '@wpic/ui'`
+
+**Props:**
+```ts
+modelValue?: string | number | (string | number)[] | null
+options?: OptionRaw[]
+multiple?: boolean
+searchable?: boolean
+label?: string
+placeholder?: string
+allLabel?: string
+maxLabels?: number
+error?: boolean
+disabled?: boolean
+size?: 'sm' | 'md' | 'lg'
+```
+
+**Emits:**
+```ts
+'update:modelValue': [v: any]
+```
+
+---
+
+## WSidePanel
+
+**Import:** `import { WSidePanel } from '@wpic/ui'`
+
+**Props:**
+```ts
+open: boolean
+title?: string
+subtitle?: string
+width?: string   // e.g. '420px', '560px' — default 420px
+zIndex?: number  // default 50
+```
+
+**Emits:**
+```ts
+close: []
+```
+
+---
+
+## WSkeleton
+
+**Import:** `import { WSkeleton } from '@wpic/ui'`
+
+**Props:**
+```ts
+width?: string
+height?: string
+rounded?: string
+```
+
+---
+
+## WSpinner
+
+**Import:** `import { WSpinner } from '@wpic/ui'`
+
+**Props:**
+```ts
+size?: 'sm' | 'md' | 'lg'   // default 'md'
+tone?: 'primary' | 'muted'  // default 'primary'
+```
+
+---
+
+## WLoader
+
+**Import:** `import { WLoader } from '@wpic/ui'`
+
+**Props:**
+```ts
+text?: string              // default 'Loading...'
+size?: 'sm' | 'md' | 'lg'  // default 'md'
+```
+
+---
+
+## WSlidePanel
+
+**Import:** `import { WSlidePanel } from '@wpic/ui'`
+
+**Props:**
+```ts
+modelValue: boolean
+title?: string
+width?: string
+```
+
+**Emits:**
+```ts
+'update:modelValue': [v: boolean]
+```
+
+---
+
+## WSlider
+
+**Import:** `import { WSlider } from '@wpic/ui'`
+
+**Props:**
+```ts
+min?: number
+max?: number
+step?: number
+disabled?: boolean
+```
+
+---
+
+## WStatCard
+
+**Import:** `import { WStatCard } from '@wpic/ui'`
+
+**Props:**
+```ts
+label: string
+value: string | number
+unit?: string
+color?: string
+sub?: string
+subColor?: string
+```
+
+---
+
+## WTable
+
+**Import:** `import { WTable } from '@wpic/ui'`
+
+**Props:**
+```ts
+data?:              Record<string, unknown>[]
+columns:            WTableColumn[]
+loading?:           boolean
+emptyText?:         string
+pageSize?:          number
+searchPlaceholder?: string
+rowClickable?:      boolean
+showHeader?:        boolean
+```
+
+**Emits:**
+```ts
+'row-click': [row: Record<string, unknown>]
+```
+
+---
+
+## WTag
+
+**Import:** `import { WTag } from '@wpic/ui'`
+
+```ts
+variant?: 'default' | 'neutral' | 'primary' | 'success' | 'warning' | 'error' | 'info' | 'overlay' | 'teal' | 'meta'
+size?: 'sm' | 'md'
+theme?: 'auto' | 'light' | 'dark'
+checkable?: boolean
+checked?: boolean // v-model:checked; controlled by the caller
+checkedVariant?: 'neutral' | 'info' | 'warning' | 'success' | 'error' // default neutral
+uncheckedAppearance?: 'normal' | 'muted' // default normal
+disabled?: boolean
+editable?: boolean
+modelValue?: string | null
+options?: PopoverOption[]
+removable?: boolean
+removeLabel?: string // default "Remove tag"; provide contextual/localized labels
+```
+
+Emits `update:checked(boolean)`, `update:modelValue(string)` and `remove()`.
+
+Checkable tags are native toggle buttons with `aria-pressed`, a 14px circle, and a custom check. They support Space and Enter. Checkable takes precedence over editable; use one interaction mode at a time. Editable tags retain the option popover. Removable interactive tags use sibling buttons, avoiding nested buttons. Disabled tags block selection, editing and removal. Borders remain subtle (5% opacity).
+
+---
+
+## WTagInput
+
+**Import:** `import { WTagInput } from '@wpic/ui'`
+
+**Props:**
+```ts
+modelValue?:         WTagItem[]
+locale?:             string
+locales?:            string[]
+recentKey?:          string
+/** Called for typeahead suggestions; return matching tags */
+searchFn?:           (q: string, locale: string) => Promise<WTagItem[]>
+/** Called on Enter with raw input; return a resolved/new tag with translations */
+resolveFn?:          (input: string, locale: string) => Promise<WTagItem>
+/** Called to persist add/remove; throw to signal failure (triggers rollback) */
+mutateFn?:           (action: 'add' | 'remove', tag: WTagItem) => Promise<void>
+placeholder?:        string
+labelRecent?:        string
+labelAutoTranslated?: string
+labelAlreadyAdded?:  string
+labelExisting?:      string
+labelNew?:           string
+labelEdit?:          string
+labelCancel?:        string
+labelConfirm?:       string
+labelErrorResolving?: string
+labelErrorAdding?:   string
+```
+
+**Emits:**
+```ts
+'update:modelValue': [tags: WTagItem[]]
+```
+
+---
+
+## WTextarea
+
+**Import:** `import { WTextarea } from '@wpic/ui'`
+
+**Props:**
+```ts
+modelValue?: string
+placeholder?: string
+rows?: number
+disabled?: boolean
+error?: boolean
+label?: string
+resize?: 'none' | 'vertical' | 'both'
+```
+
+**Emits:**
+```ts
+'update:modelValue': [string]
+```
+
+---
+
+## WToggle
+
+**Import:** `import { WToggle } from '@wpic/ui'`
+
+**Props:**
+```ts
+disabled?: boolean
+```
+
+---
+
+## WTooltip
+
+**Import:** `import { WTooltip } from '@wpic/ui'`
+
+**Props:**
+```ts
+content: string
+placement?: 'top' | 'bottom' | 'left' | 'right'
+delay?: number
+```
+
+---