@umbra.ui/core 0.4.6 → 0.5.0

package/src/skills/umbra.ui-picker-date/SKILL.md

@@ -0,0 +1,36 @@
+# Umbra Skill: DatePicker
+
+Use this skill for date selection with compact/full calendar views and optional custom trigger labels.
+
+## When To Use
+- You need a single-date picker bound to a `Date` model.
+- You need a popover calendar with smart positioning.
+- You want custom trigger visuals via the `label` slot.
+
+## Required Context Checklist
+- Bound date state location (`v-model:date`) and submit behavior.
+- Timezone/display expectations (local date formatting).
+- Whether to keep default label UI or provide a custom `#label` slot.
+- Validation rules that remain in parent (min/max/business constraints).
+
+## Ask Developer If Missing
+- "Should selected dates be interpreted in local time or normalized before submit?"
+- "Do we need a custom trigger label design or default DatePicker label?"
+- "What date constraints should the parent enforce?"
+
+## Implementation Recipe
+1. Import `DatePicker`.
+2. Bind `v-model:date` to a `ref<Date>`.
+3. Optionally handle `@update:date` for side effects.
+4. For custom trigger UI, provide `#label` (or set `:label="false"` to hide).
+5. Keep business validation in parent and surface errors separately.
+
+## Validation And Edge Cases
+- Ensure parent can handle timezone-sensitive dates consistently.
+- Avoid mutating shared `Date` instances unexpectedly in parent logic.
+- Verify open/close and selection behavior with keyboard and pointer.
+
+## Definition Of Done
+- Date selection updates parent state reliably via `v-model:date`.
+- Trigger behavior matches design (default/custom/hidden label).
+- Parent validation and submit flow handle invalid ranges gracefully.

package/src/skills/umbra.ui-picker-date/reference.md

@@ -0,0 +1,26 @@
+# Reference: DatePicker
+
+Source of truth:
+- `packages/core/src/components/pickers/DatePicker/DatePicker.vue`
+- `packages/core/src/components/pickers/DatePicker/README.md`
+
+## Public Props
+- `date: Date`
+- `label?: boolean` (default `true`)
+
+## Slots
+- `label` -> custom trigger content (default label rendering is fallback)
+
+## Emitted Events
+- `update:date` -> selected `Date`
+
+## Integration Notes
+- Custom trigger styling can target:
+  - `data-date-picker-button`
+  - `data-date-picker-open="true|false"`
+- Parent should own min/max/business validation rules.
+
+## Agent Verification Checklist
+- `v-model:date` updates on day selection.
+- Custom `#label` renders and default trigger visuals are not forced.
+- `:label="false"` hides trigger label content.

package/src/skills/umbra.ui-picker-file/SKILL.md

@@ -0,0 +1,42 @@
+# Umbra Skill: FilePicker
+
+Use this skill for drag-and-drop file selection with validation, optional directory traversal, and customizable overlay states.
+
+## When To Use
+- You need drag-and-drop plus click-to-upload file intake.
+- You need file type/size/count constraints at input time.
+- You need custom empty/overlay/processing UI using slots.
+
+## Required Context Checklist
+- Accepted file types and max file size/count constraints.
+- Whether uploads append or replace existing selections.
+- Whether directory traversal is allowed (`recursive`).
+- Error handling strategy for `error` payloads.
+- Whether parent needs programmatic controls via `defineExpose`.
+
+## Ask Developer If Missing
+- "What exact file-type constraints and max sizes should apply?"
+- "Should newly dropped files append or replace current files?"
+- "Do we allow dropping folders recursively?"
+- "What should happen with validation failures in UI?"
+
+## Implementation Recipe
+1. Import `FilePicker` and bind `v-model:files`.
+2. Configure `accept`, `maxSize`, `maxFiles`, `multiple`, `appendFiles`.
+3. Handle:
+   - `@update:files` for state sync
+   - `@error` for validation messages
+   - `@drop` for incremental side effects
+4. Add optional slots (`default`, `overlay`, `processing`) as needed.
+5. Use `ref` + exposed methods for programmatic open/clear when required.
+
+## Validation And Edge Cases
+- Confirm extension + MIME matching is correct for your accept list.
+- Handle single-file mode (`multiple=false`) and replacement semantics.
+- Guard against large batch drops and folder recursion depth expectations.
+- Ensure disabled state blocks interaction and visual state changes.
+
+## Definition Of Done
+- File selection flow works for drag-drop and dialog.
+- Validation errors surface clearly and deterministically.
+- Parent receives correct file arrays and reacts to updates reliably.

package/src/skills/umbra.ui-picker-file/reference.md

@@ -0,0 +1,39 @@
+# Reference: FilePicker
+
+Source of truth:
+- `packages/core/src/components/pickers/FilePicker/FilePicker.vue`
+- `packages/core/src/components/pickers/FilePicker/README.md`
+
+## Public Props
+- `accept?: string | string[]` (default `"*/*"`)
+- `multiple?: boolean` (default `true`)
+- `disabled?: boolean` (default `false`)
+- `maxSize?: number` (default `Infinity`)
+- `maxFiles?: number` (default `Infinity`)
+- `recursive?: boolean` (default `true`)
+- `appendFiles?: boolean` (default `true`)
+
+## Events
+- `update:files` -> `File[]`
+- `error` -> `FileError[]`
+- `drop` -> newly dropped `File[]`
+
+## Slots
+- default slot -> idle dropzone content
+- `overlay` -> drag-over overlay UI
+- `processing` -> while files are being processed
+
+## Exposed Methods/State
+- `openFileDialog()`
+- `clearFiles()`
+- `files` (reactive files ref)
+- `errors` (reactive errors ref)
+
+## Types
+- `FileError`: `{ file: string; error: string }`
+- `DropState`: `{ isDragging: boolean; isProcessing: boolean; dragCount: number }`
+
+## Agent Verification Checklist
+- Accepted/rejected file behavior matches `accept`, `maxSize`, `maxFiles`.
+- `appendFiles` vs replace behavior is correct for product flow.
+- `error` payloads are surfaced in UI and are actionable.

package/src/skills/umbra.ui-picker-icon/SKILL.md

@@ -0,0 +1,36 @@
+# Umbra Skill: IconPicker
+
+Use this skill for selecting icon keys from `@umbra.ui/icons` with optional custom trigger rendering.
+
+## When To Use
+- You need to store an icon key (`IconKey`/string) from Umbra icons.
+- You need optional custom icon subsets (`iconList`).
+- You need custom trigger UI through the `label` slot.
+
+## Required Context Checklist
+- Selected icon state and storage format.
+- Whether to use default icon catalog or constrained `iconList`.
+- Whether popup must be disabled (`preventPopup`).
+- Trigger style choice: default icon trigger vs custom `#label`.
+
+## Ask Developer If Missing
+- "Do you want all icons or a curated icon subset?"
+- "Should icon picker be interactive or display-only (`preventPopup`)?"
+- "Do you need custom trigger styling via `#label`?"
+
+## Implementation Recipe
+1. Import `IconPicker`.
+2. Bind `v-model:icon` to `ref<IconKey | string>`.
+3. Provide `:icon-list` when domain-specific icon choices are needed.
+4. Handle `@update:icon` for side effects.
+5. Provide `#label` if trigger visuals must be fully custom.
+
+## Validation And Edge Cases
+- Ensure icon keys passed in `iconList` exist in `@umbra.ui/icons`.
+- Handle empty/unknown icon values gracefully in parent model.
+- Verify constrained lists still include currently selected value.
+
+## Definition Of Done
+- Selection emits and model binding are stable.
+- Curated icon list behavior is correct.
+- Trigger behavior matches requirements (default/custom/hidden label).

package/src/skills/umbra.ui-picker-icon/reference.md

@@ -0,0 +1,28 @@
+# Reference: IconPicker
+
+Source of truth:
+- `packages/core/src/components/pickers/IconPicker/IconPicker.vue`
+- `packages/core/src/components/pickers/IconPicker/README.md`
+
+## Public Props
+- `icon: string`
+- `pickerOffsetX: number` (default `0`)
+- `preventPopup: boolean` (default `false`)
+- `label?: boolean` (default `true`)
+- `iconList?: IconKey[]`
+- `iconSize?: number` (default `18`)
+
+## Slots
+- `label` -> custom trigger content
+
+## Events
+- `update:icon` -> selected icon key (`string`)
+
+## Integration Notes
+- Default icon list excludes animated keys (`*anim*`).
+- `iconList` overrides the default list and should contain valid keys.
+
+## Agent Verification Checklist
+- `v-model:icon` updates to selected icon key.
+- Custom `iconList` limits choices as expected.
+- Custom `#label` and `:label="false"` work correctly.