@wpic/ui 0.3.15 → 0.4.0

package/CHANGELOG.md

@@ -0,0 +1,23 @@
+# Changelog
+
+## 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,635 @@
+# COMPONENTS.md — wpic-ui component reference
+Use this as reference when writing Vue components. Updated for 0.4.0.
+
+## 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
+```
+
+---

package/dist/components/WAlert.vue.d.ts

@@ -1,20 +1,20 @@
+import { WTheme } from './semantic/styles';
+/** Compatibility entry point. Prefer WBanner for new contextual messages. */
 type __VLS_Props = {
     variant?: 'info' | 'success' | 'warning' | 'error';
     title?: string;
     dismissible?: boolean;
+    theme?: WTheme;
 };
-declare var __VLS_5: {};
+declare var __VLS_9: {};
 type __VLS_Slots = {} & {
-    default?: (props: typeof __VLS_5) => any;
+    default?: (props: typeof __VLS_9) => any;
 };
-declare const __VLS_component: import('vue').DefineComponent<__VLS_Props, {}, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {} & {
+declare const __VLS_component: import('vue').DefineComponent<__VLS_Props, {}, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {
     close: () => any;
 }, string, import('vue').PublicProps, Readonly<__VLS_Props> & Readonly<{
     onClose?: (() => any) | undefined;
-}>, {
-    variant: "info" | "success" | "warning" | "error";
-    dismissible: boolean;
-}, {}, {}, {}, string, import('vue').ComponentProvideOptions, false, {}, any>;
+}>, {}, {}, {}, {}, string, import('vue').ComponentProvideOptions, false, {}, any>;
 declare const _default: __VLS_WithSlots<typeof __VLS_component, __VLS_Slots>;
 export default _default;
 type __VLS_WithSlots<T, S> = T & {

package/dist/components/WBadge.vue.d.ts

@@ -1,17 +1,26 @@
 import { Component } from 'vue';
+import { WTheme } from './semantic/styles';
 type __VLS_Props = {
-    variant?: 'default' | 'primary' | 'success' | 'warning' | 'error' | 'info';
+    variant?: 'default' | 'neutral' | 'primary' | 'success' | 'warning' | 'error' | 'info';
     size?: 'sm' | 'md';
     dot?: boolean;
     icon?: Component;
-    /** Show a border. Default: false (no border). */
+    /** Defaults to false for compatibility. Enable for the outlined lab treatment. */
     bordered?: boolean;
+    /** Compact numerical indicator; provide an accessible label when context is not visible. */
+    count?: boolean;
+    theme?: WTheme;
 };
 declare var __VLS_5: {};
 type __VLS_Slots = {} & {
     default?: (props: typeof __VLS_5) => any;
 };
-declare const __VLS_component: import('vue').DefineComponent<__VLS_Props, {}, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {}, string, import('vue').PublicProps, Readonly<__VLS_Props> & Readonly<{}>, {}, {}, {}, {}, string, import('vue').ComponentProvideOptions, false, {}, any>;
+declare const __VLS_component: import('vue').DefineComponent<__VLS_Props, {}, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {}, string, import('vue').PublicProps, Readonly<__VLS_Props> & Readonly<{}>, {
+    variant: "default" | "neutral" | "primary" | "success" | "warning" | "error" | "info";
+    size: "sm" | "md";
+    theme: WTheme;
+    bordered: boolean;
+}, {}, {}, {}, string, import('vue').ComponentProvideOptions, false, {}, any>;
 declare const _default: __VLS_WithSlots<typeof __VLS_component, __VLS_Slots>;
 export default _default;
 type __VLS_WithSlots<T, S> = T & {