Files
front-ui-registry/.agent/consumer.md

56 lines
4.6 KiB
Markdown

## KriUiRegistry Consumer Contract
When implementing or changing frontend UI, use this order:
1. Reuse an existing shared component in the project when it already meets the requirement.
2. Prefer an approved component from KriUiRegistry.
3. Otherwise, prefer a suitable shadcn/ui component.
4. Create a custom component only when the preceding options cannot meet the requirement safely.
### KriAutoComplete Search Scroll
- `kri-auto-complete` exposes `resetScrollOnSearch?: boolean` on `KriSingleSelect`, `KriMultiSelect`, and `MultiSelect`. It defaults to `false`, preserving existing behavior.
- When enabled, a search value change (including clearing it) resets the option list scroll to the top on the next animation frame in both `filter` and `inputOnly` modes. Async result updates alone do not trigger another reset.
### KriAutoComplete Option Tooltip
- `kri-auto-complete` exposes `optionTooltip?: 'singleLine' | 'wrap'` and `optionTooltipClassName?: string` on `KriSingleSelect`, `KriMultiSelect`, and `MultiSelect`. It is off by default, preserving existing behavior.
- When enabled, hovering an option shows its full `label` in a right-side tooltip. `singleLine` stays on one line until the available viewport width; `wrap` wraps at 28rem. The item depends on the shadcn `tooltip` component and provides its own `TooltipProvider`.
### KriAutoComplete Search Match
- `kri-auto-complete` exposes `searchMatch?: 'fuzzy' | 'contains'` on `KriSingleSelect`, `KriMultiSelect`, and `MultiSelect`. It defaults to `fuzzy` (cmdk's default subsequence scoring), preserving existing behavior.
- `contains` keeps only options whose label or value contains the search text as a case-insensitive substring, in the original option order. It applies only when `searchMode` is `filter`.
### KriColorPalette
- `kri-color-palette` provides `KriColorPalette` with `value: string | null` and `onChange(value: string | null)`. Values are uppercase `#RRGGBB`, or `#RRGGBBAA` when they carry transparency; `null` means no color.
- `allowAlpha?: boolean` defaults to `false`. When disabled, an incoming `#RRGGBBAA` value is still displayed and preserved until the user picks a new color, which produces an opaque `#RRGGBB`. When enabled, a transparency slider and `#RRGGBBAA` input are available.
- `colors`, `allowCustom`, `allowClear`, `disabled`, `placeholder`, `className`, and `aria-label` are optional. A disabled palette never opens.
- Color helpers (`parseHexColor`, `formatHexColor`, `normalizeHexColor`, `isLightHexColor`) ship in `color-palette/color.ts`. Render stored colors as solid backgrounds without extra opacity so they match the palette.
### KriEditor Preview Options
- With `enableImageMap` and `showPreview`, the WYSIWYG preview overlays `<area>` regions (rect/circle/poly); without `enableImageMap` nothing changes.
- `smsFrameClassName?: string` appends classes to the SMS preview phone frame (for example, overriding the default `h-[600px]`).
- `renderToolbarEnd` is rendered through an internal slot component; when the prop is provided, the toolbar separator is always shown even if the function returns `null`.
- Installed copies may diverge locally; compare against the registry source before reinstalling with overwrite.
### KriEditor SMS Preview
- `changeSmsType` reports `SMS | LMS | MMS`. Update consumer callbacks to handle `MMS`; this widens the previous callback contract.
- Attachment presence (`smsHasAttachment`) takes priority and reports MMS. Otherwise a title or UTF-8 preview size >= `smsMaxBytes` (default 90) reports LMS; the remainder reports SMS. LMS/MMS share `lmsMaxBytes` (default 2000).
- UTF-8 byte counting includes `smsPreviewSuffix` and its separating newline, without storing the suffix in the body.
- This is a preview. Use the template-save response for saved `tmplatTy` and delivery-result `sendTy` for actual per-recipient type after server substitution. Registry updates require updating installed consumer copies.
### Required Shared References
Before each related task, read the current contents of every matching reference, even if it was read earlier in the session.
| Task scope | Required reference |
|---|---|
| Installing, upgrading, adapting, or verifying a registry component | `.agent-harness/references/kri-ui-registry/installation-and-adaptation.md` |
| KriEditor HTML, image-map, sanitizer, or WYSIWYG compatibility | `.agent-harness/references/kri-ui-registry/editor-html-compatibility.md` |
If a task spans multiple scopes, read every matching reference. Generated files under `.agent-harness/references/` are read-only copies; edit KriUiRegistry's `.agent/consumer.md` or `.agent/consumer-references/` and recompose instead.