# kView UI Core

`kview/ui-core` owns the portable visual foundation: tokens, icons, buttons,
forms, dropdowns, date pickers, tabs, navigation primitives, feedback, loading,
floating-layer behavior, and the shared Blade component path.

Laravel discovers `Kview\UiCore\UiCoreServiceProvider` automatically. Consumer
applications keep using the stable component names such as `<x-ui.icon>` and
`<x-ui.icon-button>`.

Vite consumers should alias `@kview/ui-core` to
`vendor/kview/ui-core/resources`, then import:

```css
@import "@kview/ui-core/css/index.css";
```

```js
import '@kview/ui-core/js/index.js';
```

Vue 3 consumers can import the optional typed source entry. Projects that use
only Blade do not import or ship these components:

```ts
import {
    KviewAvatar,
    KviewBentoGrid,
    KviewBentoItem,
    KviewBreadcrumbs,
    KviewButton,
    KviewCard,
    KviewCombobox,
    KviewConfirmDialog,
    KviewDatePicker,
    KviewDialog,
    KviewDropdown,
    KviewMoneyInput,
    KviewMultiSelect,
    KviewPageHeader,
    KviewPopover,
    KviewTabs,
    KviewToastProvider,
    KviewTooltip,
    KviewUiProvider,
    useKviewToast,
} from '@kview/ui-core/vue';
```

The Vue entry covers the portable UI components: `KviewIcon`, `KviewButton`,
`KviewButtonGroup`, `KviewCard`, `KviewCombobox`, `KviewConfirmDialog`,
`KviewDatePicker`, `KviewIconButton`,
`KviewTooltip`, `KviewAlert`, `KviewLoadingState`, `KviewEmptyState`,
`KviewFormField`, `KviewTextInput`,
`KviewTextarea`, `KviewMoneyInput`, `KviewPercentInput`, `KviewFormActions`,
`KviewResourceHeading`, `KviewPageHeader`, `KviewResourceHeader`,
`KviewSectionHeader`, `KviewBreadcrumbs`, `KviewTabs`,
`KviewSegmentedControl`, `KviewToggle`, `KviewAvatar`, `KviewPopover`,
`KviewDialog`, `KviewDropdown`, `KviewMultiSelect`, `KviewBentoGrid`,
`KviewBentoItem`, and `KviewToastProvider`. `KviewUiProvider` is also public,
and `useKviewToast` exposes the toast
command API to descendants of
the toast provider. They consume the same CSS entry, tokens, icon catalog, and
accessible contracts as the Blade API. Vue and TypeScript remain host build
dependencies rather than Composer runtime dependencies.

`KviewDialog`, `KviewDropdown`, and `KviewCombobox` use Reka UI internally for
accessible modal, select/listbox, and autocomplete mechanics;
`KviewConfirmDialog` composes the former as a safe, typed alert-dialog.
`KviewDatePicker` composes the package popover and historical calendar
presentation while a normalized native date input retains Laravel submission.
Its visible value automatically switches from the localized long label to a
localized numeric short date when the control itself is too narrow, without
changing the submitted ISO value.

`KviewMultiSelect` composes the public popover and checkbox primitives. Its
menu remains open while options are toggled, optionally filters a long option
list, and submits repeated `name[]` hidden values. An empty selection is left
for the host to interpret (for example, Dashboard filters use it as “all”).
Required instances use native form validity, disabled instances omit their
values from submission, and Clear preserves selected disabled options. The
component never fetches options or owns a route.

`KviewBentoGrid` and `KviewBentoItem` are render-only responsive layout
primitives. The grid owns column, gap, span, row-span and container-breakpoint
behavior; it deliberately adds no border, background, padding or shadow. Put
existing cards, charts and panels inside its items so those content primitives
own their presentation. Spans larger than the configured column count become
full-width, and the container collapses `4 → 2 → 1` or `3 → 1` before a narrow
side panel becomes unreadable. A host may still place the whole composition in
an existing page-section surface; the bento primitives never create one.
The package manifest declares `reka-ui` and Vue
as peer dependencies; consumers of the optional Vue entry install compatible
versions but import only the public kView components. A source-alias fixture
must resolve these peers from the host project, as the clean consumer does for
Reka. Blade-only consumers do not import the optional Vue entry and therefore
need neither peer in their browser build. Reka supplies no kView INVESTOR colors,
typography, padding, radii, shadows, or application routes; those remain owned
by the shared kView CSS and the host composition.

Wrap a Vue application once with `KviewUiProvider` to replace the explicit
English defaults with host translations and resource icons. The serialized
`messages` and `resourceIcons` values can come from Laravel/Inertia; the
optional `linkComponent` is supplied locally by the Vue host and is never part
of the server payload:

```vue
<KviewUiProvider
    :messages="page.props.ui.messages"
    :resource-icons="page.props.ui.resourceIcons"
    :link-component="AppLink"
>
    <App />
</KviewUiProvider>
```

Components still work without a provider through `defaultKviewUiMessages`.
Custom package consumers may call `useKviewUi()` inside their own adapters.
`KviewEmptyState` keeps actions native unless `actionInertia` is explicit, and
`KviewAlert.resetKey` lets a host reveal a newly delivered flash after local
dismissal.
`AppLink` is a host-owned example: it can choose an Inertia link for migrated
destinations and a native anchor for server-rendered routes. A host adapter must
preserve consumer ARIA, allow a disabled package control to cancel navigation,
and expose focus on the rendered anchor. The package never imports Inertia
itself.

`x-ui.card` and `KviewCard` share the same framed surface, default/compact
header and body insets, radius, divider, shadow, and container context.
`KviewPageHeader` also exposes a `detail` variant for compact Back/title/action
record headers. These are presentation contracts only: routes, data formatting,
and business composition remain host-owned.

Blade, legacy JavaScript, and Vue resolve icons from the same package-owned
`resources/icons/kview-icons.json` catalog. It is the only owner of icon names,
legacy aliases, SVG geometry, and the `external` fallback. TypeScript consumers
can import the derived `KviewIconName`, `KviewIconAlias`, and
`KviewIconIdentifier` types from `@kview/ui-core/js/icon-registry` when the
package source alias is available.

Use `php artisan vendor:publish --tag=kview-ui-core-config` to publish
configuration. Publishing `kview-ui-core-assets` is optional for hosts that
cannot compile source directly from `vendor/`.

English and French translations ship with the package. Publish host overrides
with `php artisan vendor:publish --tag=kview-ui-core-translations`.