@featherk/ui

Vue 3 components built on Kendo UI for Vue and driven by @featherk/composables.

Components Overview

• Address: USAddress - Presentational US address renderer driven by a parent-owned useUSAddress view model.
  • Component guide: docs/address/USAddress.md
• Table: ActionCell - Configurable repeatable action-button container driven by a parent-owned shared popup lifecycle.
  • Component guide: docs/table/ActionCell.md
  • Composable guide: docs/table/useActionCellMenu.md
• Picker: DateField - Kendo DatePicker with a masked input, driven by a parent-owned useMaskedDateInput.
  • Component guide: docs/picker/DateField.md
• Picker: TimeField - Kendo TimePicker with a masked input, driven by a parent-owned useMaskedTimeInput.
  • Component guide: docs/picker/TimeField.md
• Picker: DateRangeField - Masked date range input with a range calendar popup, driven by a parent-owned useMaskedDateRangeInput.
  • Component guide: docs/picker/DateRangeField.md

Importing Components

Import from the feature subpath. Each subpath is a separate entry that imports only its own components, styles and peer dependencies at runtime, which also keeps the dev server fast. The package root re-exports every feature; see What Gets Installed vs. What Ships. Don't import internal dist paths.

import { USAddress } from "@featherk/ui/address";
import { ActionCell } from "@featherk/ui/table";
import { DateField, DateRangeField, TimeField } from "@featherk/ui/picker";
import { useUSAddress } from "@featherk/composables/address";

For complete setup, behavior, and examples, use the component guide listed in Components Overview.

What Gets Installed vs. What Ships

FeatherK packages should just work once installed: you should never have to track down a missing dependency or silence a peer warning. When that conflicts with install size, FeatherK accepts a larger node_modules and keeps the browser bundle small.

| You import | Installed in node_modules | Shipped to the browser (production build) | | -------------------------------------------- | ------------------------------------------- | ----------------------------------------- | | import { X } from "@featherk/ui/<feature>" | All required peers, installed automatically | X, its styles and the peers it imports | | import { X } from "@featherk/ui" | Same | Same as the subpath import | | Nothing from a feature | Its peers are still installed | Nothing from that feature |

During vite dev, a root import loads every feature. This affects only the dev server, not what users download.

Kendo UI Compatibility

Built and tested against Kendo UI for Vue 6.4.1. Kendo packages are declared as peer dependencies (^6.4.1), so your application controls the installed Kendo version.

| Subpath | Components | Kendo packages | | --------- | ------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------- | | address | USAddress | kendo-vue-dropdowns, kendo-vue-inputs, kendo-vue-labels | | table | ActionCell, useActionCellMenu | kendo-vue-buttons, kendo-vue-grid | | picker | DateField, TimeField, DateRangeField | kendo-vue-common, kendo-vue-dateinputs, kendo-vue-inputs, kendo-vue-labels, kendo-vue-popup, kendo-vue-tooltip |

Dependencies

• Required peers: vue (3.5+), @featherk/composables, @featherk/icons, @progress/kendo-vue-buttons, @progress/kendo-vue-common, @progress/kendo-vue-dateinputs, @progress/kendo-vue-dropdowns, @progress/kendo-vue-grid, @progress/kendo-vue-inputs, @progress/kendo-vue-labels, @progress/kendo-vue-popup, @progress/kendo-vue-tooltip

  npm and pnpm install these automatically; with Yarn Berry, install them yourself. Each subpath loads only the ones its components use, so an app that never imports @featherk/ui/picker never loads @featherk/icons or @progress/kendo-vue-tooltip.

• Optional peers:

  • @progress/kendo-vue-layout, for useActionCellMenu — its menuProps are spread onto a shared Kendo <Menu>
  • @progress/kendo-svg-icons (types only) — used by ActionCell icon typings

• Runtime dependencies: none. Everything is a peer, so your app and FeatherK share one copy of Vue, Kendo and @featherk/composables.

Keep all @featherk/* packages on the same version. They release together, and each @featherk/ui release requires at least the matching @featherk/composables and @featherk/icons. With Renovate or Dependabot, group them into one update.

Styling

Component styles ship with @featherk/ui. Each ES entry imports the styles for its own components, so nothing needs to be imported separately. The CommonJS build (require) does not import CSS. Theme styles for the Kendo components come from @featherk/styles.

Testing with Vitest

Vitest leaves installed packages to Node, and Node can't load the stylesheets each entry imports. Without this setting, tests that import @featherk/ui fail with Unknown file extension ".css":

// vitest.config.ts
export default defineConfig({
  test: {
    server: { deps: { inline: ["@featherk/ui"] } },
  },
});

To mock a composable, mock its subpath, not the package root. Each subpath is a separate module, and a mock replaces only the module it names. FeatherK components import composables from their subpaths, so a root mock never reaches them. For example, TimeField imports usePopupTrap from @featherk/composables/trap:

// Before 0.18.0 every subpath was one module, so this also reached TimeField.
vi.mock("@featherk/composables", …);

// Now: mock the subpath.
vi.mock("@featherk/composables/trap", …);

Import from the same subpath in your own code too. A subpath mock doesn't reach code that imports from the root.

Build

Run from repository root:

npm run build -- --filter=@featherk/ui

Or run package-local:

npm run build

Maintainer Notes

• Every feature folder has an index.ts barrel, is re-exported from src/index.ts, and has a matching exports subpath.
• vite.config.ts builds one ES and one CommonJS entry for the root and for each package.json exports subpath (address, table, picker). A new feature folder only needs its subpath added to exports.
• Scoped component styles are split per feature, and a small Vite plugin imports each chunk's CSS from its ES module. New components get their styles with no extra step.
• package.json lists only CSS in sideEffects, so a root import tree-shakes to the same code and styles as the subpath. Keep other modules free of import-time side effects, or add them to sideEffects.
• Keep shared state out of module scope: no module-level refs, Maps or provide/inject keys. An app can load both the ES and CommonJS builds, and the two copies don't share state. Create state in the component or composable and pass the instance, as useActionCellMenu does.
• The repo's scripts/check-entries.mjs runs at the end of the build. It fails if an export target is missing, an entry imports an undeclared peer, any entry imports an optional peer (npm doesn't install those), or a stylesheet is not imported.
• The repo's scripts/check-peers.mjs runs after it. It fails unless each @featherk/* peer range is >=x.y.z with a minimum of at least that sibling's current version, so npm never pairs this release with an older sibling that lacks what it imports. Packages release in lockstep, so the root version:patch|minor|major scripts run scripts/sync-peers.mjs, which raises these minimums to the new version in package.json and package-lock.json.
• For new component documentation, follow the docs authoring template in docs/README.md.

Changelog

Release history for all @featherk/* packages is maintained in a single CHANGELOG.md.