@frigear-nu/widget 0.0.0-stage → 0.0.1

package/README.md

@@ -1,3 +1,5 @@
-# Temporary Holding Version
+# @frigear-nu/widget
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Named widget areas that modules contribute Vue components to and hosts render with `<WidgetArea>`; `extendWidgets` at build time, ordering, lazy loading and a `widgets:filter` hook for gating. Modelled on `@frigear-nu/menu`.
+
+See the [documentation](../../apps/docs/content/4.modules/19.widget.md) for usage.

package/dist/module.d.mts

@@ -0,0 +1,73 @@
+import * as _nuxt_schema from '@nuxt/schema';
+
+/**
+ * A widget: a Vue component a module contributes to a named area (e.g. `admin.dashboard`). The data is
+ * presentation-free - the host decides how an area is laid out - and serializable, so the registry can be
+ * generated at build time. Components are loaded lazily, only when their area is rendered.
+ */
+type WidgetDefinition = {
+    /** Stable identifier within an area; derived from the component file name when omitted. */
+    id?: string;
+    /** Resolved path of the widget's Vue component (e.g. `resolver.resolve('./runtime/app/widgets/Foo.vue')`). */
+    component: string;
+    /** Lower numbers render first. Widgets without an `order` render last, in registration order. */
+    order?: number;
+    /** How many grid columns the widget spans in the default `<WidgetArea>` layout (1-4). Defaults to 1. */
+    span?: 1 | 2 | 3 | 4;
+    /** Serializable props passed to the component. */
+    props?: Record<string, unknown>;
+    /**
+     * A free-form requirement (a role, an ability name, a feature flag...) that a `widgets:filter` listener can
+     * act on to hide the widget. The widget module itself never interprets it.
+     */
+    requires?: string;
+    tags?: string[];
+    meta?: Record<string, unknown>;
+};
+/** A registered widget with its area and a guaranteed `id`. */
+type RegisteredWidget = WidgetDefinition & {
+    id: string;
+    area: string;
+};
+/** What `useWidgets` returns: everything but the component, which is resolved by `<WidgetArea>`. */
+type WidgetMeta = Omit<RegisteredWidget, 'component'>;
+type ModuleOptions = Record<string, never>;
+/**
+ * A tab: a Vue component a module contributes to a named area (e.g. `admin.users`) that the host renders with
+ * `<WidgetTabs>`. Tabs live in their own registry, separate from widgets, with the same ordering and gating.
+ */
+type TabDefinition = {
+    /** Stable identifier within an area; derived from the component file name when omitted. Used as the `?tab=` value. */
+    id?: string;
+    /** Resolved path of the tab's Vue component. */
+    component: string;
+    /** Lower numbers render first. Tabs without an `order` render last, in registration order. */
+    order?: number;
+    /** Serializable props passed to the component, next to the host's runtime `context`. */
+    props?: Record<string, unknown>;
+    /** Plain label, used when `labelKey` is missing or can't be translated. Defaults to the id. */
+    label?: string;
+    /** i18n key for the label, translated at render time when `@nuxtjs/i18n` is installed. */
+    labelKey?: string;
+    /** Icon name shown next to the label (e.g. `i-lucide-credit-card`). */
+    icon?: string;
+    /** A free-form requirement that a `tabs:filter` listener can act on; the widget module never interprets it. */
+    requires?: string;
+    tags?: string[];
+    meta?: Record<string, unknown>;
+};
+/** A registered tab with its area and a guaranteed `id`. */
+type RegisteredTab = TabDefinition & {
+    id: string;
+    area: string;
+};
+/** What `useTabs` returns: everything but the component, with the label already translated. */
+type TabMeta = Omit<RegisteredTab, 'component' | 'labelKey' | 'label'> & {
+    label: string;
+    labelKey?: string;
+};
+
+declare const _default: _nuxt_schema.NuxtModule<ModuleOptions, ModuleOptions, false>;
+
+export { _default as default };
+export type { ModuleOptions, RegisteredTab, RegisteredWidget, TabDefinition, TabMeta, WidgetDefinition, WidgetMeta };

package/dist/module.json

@@ -0,0 +1,9 @@
+{
+  "name": "@frigear-nu/widget",
+  "configKey": "widgets",
+  "version": "0.0.1",
+  "builder": {
+    "@nuxt/module-builder": "1.0.3",
+    "unbuild": "unknown"
+  }
+}

package/dist/module.mjs

@@ -0,0 +1,54 @@
+import { defineNuxtModule, createResolver, addImports, addComponent, addTypeTemplate } from '@nuxt/kit';
+import { registerModule, registerTailwindSource, defineVirtualRegistry } from '@frigear-nu/module-kit/utils';
+import { sortWidgets } from '../dist/runtime/utils/sort.js';
+
+const module$1 = defineNuxtModule({
+  meta: { name: "@frigear-nu/widget", configKey: "widgets" },
+  setup(_options, nuxt) {
+    registerModule("@frigear-nu/widget", nuxt);
+    const resolver = createResolver(import.meta.url);
+    registerTailwindSource(nuxt, resolver.resolve("./runtime/app"));
+    addImports([
+      { name: "useWidgets", from: resolver.resolve("./runtime/app/composables/useWidgets") },
+      { name: "useTabs", from: resolver.resolve("./runtime/app/composables/useTabs") }
+    ]);
+    addComponent({ name: "WidgetArea", filePath: resolver.resolve("./runtime/app/components/WidgetArea.vue") });
+    addComponent({ name: "WidgetTabs", filePath: resolver.resolve("./runtime/app/components/WidgetTabs.vue") });
+    addTypeTemplate({
+      filename: "types/widgets-registry.d.ts",
+      getContents: () => `declare module '#widgets/registry' {
+  import type { Component } from 'vue'
+  import type { WidgetMeta } from ${JSON.stringify(resolver.resolve("./types"))}
+  export const widgets: Record<string, Array<WidgetMeta & { component: () => Promise<{ default: Component }> }>>
+}
+declare module '#widgets/tabs' {
+  import type { Component } from 'vue'
+  import type { RegisteredTab } from ${JSON.stringify(resolver.resolve("./types"))}
+  export const tabs: Record<string, Array<Omit<RegisteredTab, 'component'> & { component: () => Promise<{ default: Component }> }>>
+}
+`
+    });
+    const lazyEntries = (areas) => Object.entries(areas).map(([area, entries]) => {
+      const items = sortWidgets(entries).map(({ component, ...meta }) => `{ ...${JSON.stringify(meta)}, component: () => import(${JSON.stringify(component)}) }`);
+      return `${JSON.stringify(area)}: [${items.join(", ")}]`;
+    }).join(", ");
+    defineVirtualRegistry(nuxt, {
+      filename: "#widgets/registry.mjs",
+      alias: "#widgets/registry",
+      collect: () => nuxt.options.widgets?._extensions ?? {},
+      contents: (areas) => `export const widgets = { ${lazyEntries(areas)} }
+`,
+      resolved: (areas) => nuxt.callHook("widgets:resolved", areas)
+    });
+    defineVirtualRegistry(nuxt, {
+      filename: "#widgets/tabs.mjs",
+      alias: "#widgets/tabs",
+      collect: () => nuxt.options.widgets?._tabs ?? {},
+      contents: (areas) => `export const tabs = { ${lazyEntries(areas)} }
+`,
+      resolved: (areas) => nuxt.callHook("tabs:resolved", areas)
+    });
+  }
+});
+
+export { module$1 as default };

package/dist/runtime/app/components/WidgetArea.d.vue.ts

@@ -0,0 +1,23 @@
+type __VLS_Props = {
+    name: string;
+    context?: Record<string, unknown>;
+};
+declare var __VLS_1: {
+    widget: any;
+    component: import("vue").Component | undefined;
+    context: Record<string, unknown> | undefined;
+}, __VLS_8: {};
+type __VLS_Slots = {} & {
+    item?: (props: typeof __VLS_1) => any;
+} & {
+    empty?: (props: typeof __VLS_8) => any;
+};
+declare const __VLS_base: 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_export: __VLS_WithSlots<typeof __VLS_base, __VLS_Slots>;
+declare const _default: typeof __VLS_export;
+export default _default;
+type __VLS_WithSlots<T, S> = T & {
+    new (): {
+        $slots: S;
+    };
+};

package/dist/runtime/app/components/WidgetArea.vue

@@ -0,0 +1,38 @@
+<script setup>
+import { getWidgetComponent } from "../utils/components";
+const props = defineProps({
+  name: { type: String, required: true },
+  context: { type: Object, required: false }
+});
+const { data: widgets } = await useWidgets(props.name, () => props.context);
+</script>
+
+<template>
+  <div
+    v-if="widgets?.length"
+    class="grid grid-cols-[repeat(auto-fit,minmax(16rem,1fr))] gap-4 md:grid-cols-4 md:[&>*]:[grid-column:span_var(--widget-span,1)]"
+  >
+    <template
+      v-for="widget in widgets"
+      :key="widget.id"
+    >
+      <slot
+        name="item"
+        :widget="widget"
+        :component="getWidgetComponent(name, widget.id)"
+        :context="context"
+      >
+        <div :style="{ '--widget-span': widget.span ?? 1 }">
+          <component
+            :is="getWidgetComponent(name, widget.id)"
+            v-bind="{ ...widget.props, ...context }"
+          />
+        </div>
+      </slot>
+    </template>
+  </div>
+  <slot
+    v-else
+    name="empty"
+  />
+</template>

package/dist/runtime/app/components/WidgetArea.vue.d.ts

@@ -0,0 +1,23 @@
+type __VLS_Props = {
+    name: string;
+    context?: Record<string, unknown>;
+};
+declare var __VLS_1: {
+    widget: any;
+    component: import("vue").Component | undefined;
+    context: Record<string, unknown> | undefined;
+}, __VLS_8: {};
+type __VLS_Slots = {} & {
+    item?: (props: typeof __VLS_1) => any;
+} & {
+    empty?: (props: typeof __VLS_8) => any;
+};
+declare const __VLS_base: 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_export: __VLS_WithSlots<typeof __VLS_base, __VLS_Slots>;
+declare const _default: typeof __VLS_export;
+export default _default;
+type __VLS_WithSlots<T, S> = T & {
+    new (): {
+        $slots: S;
+    };
+};

package/dist/runtime/app/components/WidgetTabs.d.vue.ts

@@ -0,0 +1,21 @@
+type __VLS_Props = {
+    name: string;
+    context?: Record<string, unknown>;
+};
+declare var __VLS_13: {};
+type __VLS_Slots = {} & {
+    empty?: (props: typeof __VLS_13) => any;
+};
+declare const __VLS_base: import("vue").DefineComponent<__VLS_Props, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
+    refresh: () => any;
+}, string, import("vue").PublicProps, Readonly<__VLS_Props> & Readonly<{
+    onRefresh?: (() => any) | undefined;
+}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+declare const __VLS_export: __VLS_WithSlots<typeof __VLS_base, __VLS_Slots>;
+declare const _default: typeof __VLS_export;
+export default _default;
+type __VLS_WithSlots<T, S> = T & {
+    new (): {
+        $slots: S;
+    };
+};

package/dist/runtime/app/components/WidgetTabs.vue

@@ -0,0 +1,82 @@
+<script setup>
+import { getTabComponent } from "../utils/tabs";
+const props = defineProps({
+  name: { type: String, required: true },
+  context: { type: Object, required: false }
+});
+const emit = defineEmits(["refresh"]);
+const route = useRoute();
+const { data: tabs } = await useTabs(props.name, () => props.context);
+const selected = ref(typeof route.query.tab === "string" ? route.query.tab : void 0);
+watch(() => route.query.tab, (tab) => {
+  if (typeof tab === "string") selected.value = tab;
+});
+const active = computed(() => tabs.value?.find((tab) => tab.id === selected.value) ?? tabs.value?.[0]);
+function select(id) {
+  selected.value = id;
+  if (!import.meta.client) return;
+  const url = new URL(window.location.href);
+  url.searchParams.set("tab", id);
+  window.history.replaceState(window.history.state, "", url);
+}
+function onKeydown(event, index) {
+  const list = tabs.value ?? [];
+  const step = event.key === "ArrowRight" ? 1 : event.key === "ArrowLeft" ? -1 : 0;
+  if (!step || !list.length) return;
+  event.preventDefault();
+  const next = list[(index + step + list.length) % list.length];
+  select(next.id);
+  nextTick(() => document.getElementById(`tab-${props.name}-${next.id}`)?.focus());
+}
+</script>
+
+<template>
+  <div
+    v-if="tabs?.length"
+    class="flex flex-col gap-6"
+  >
+    <div
+      role="tablist"
+      class="flex gap-1 overflow-x-auto overflow-y-hidden border-b border-default"
+    >
+      <button
+        v-for="(tab, index) in tabs"
+        :id="`tab-${name}-${tab.id}`"
+        :key="tab.id"
+        type="button"
+        role="tab"
+        :aria-selected="tab.id === active?.id"
+        :aria-controls="`tabpanel-${name}`"
+        :tabindex="tab.id === active?.id ? 0 : -1"
+        class="inline-flex shrink-0 items-center gap-2 border-b-2 px-3 py-2 text-sm font-medium transition-colors"
+        :class="tab.id === active?.id ? 'border-primary text-highlighted' : 'border-transparent text-muted hover:text-default'"
+        @click="select(tab.id)"
+        @keydown="onKeydown($event, index)"
+      >
+        <UIcon
+          v-if="tab.icon"
+          :name="tab.icon"
+          class="size-4"
+        />
+        {{ tab.label }}
+      </button>
+    </div>
+    <div
+      v-if="active"
+      :id="`tabpanel-${name}`"
+      role="tabpanel"
+      :aria-labelledby="`tab-${name}-${active.id}`"
+    >
+      <component
+        :is="getTabComponent(name, active.id)"
+        :key="active.id"
+        v-bind="{ ...active.props, ...context }"
+        @refresh="emit('refresh')"
+      />
+    </div>
+  </div>
+  <slot
+    v-else
+    name="empty"
+  />
+</template>

package/dist/runtime/app/components/WidgetTabs.vue.d.ts

@@ -0,0 +1,21 @@
+type __VLS_Props = {
+    name: string;
+    context?: Record<string, unknown>;
+};
+declare var __VLS_13: {};
+type __VLS_Slots = {} & {
+    empty?: (props: typeof __VLS_13) => any;
+};
+declare const __VLS_base: import("vue").DefineComponent<__VLS_Props, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
+    refresh: () => any;
+}, string, import("vue").PublicProps, Readonly<__VLS_Props> & Readonly<{
+    onRefresh?: (() => any) | undefined;
+}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+declare const __VLS_export: __VLS_WithSlots<typeof __VLS_base, __VLS_Slots>;
+declare const _default: typeof __VLS_export;
+export default _default;
+type __VLS_WithSlots<T, S> = T & {
+    new (): {
+        $slots: S;
+    };
+};

package/dist/runtime/app/composables/useTabs.d.ts

@@ -0,0 +1,9 @@
+import { type MaybeRefOrGetter } from 'vue';
+import type { TabMeta } from '../../../types.js';
+/**
+ * The tabs registered for an area, ordered, with labels translated (`labelKey`, falling back to `label`, then
+ * the id) and passed through the `tabs:filter` hook, as plain data (the component itself is resolved by
+ * `<WidgetTabs>`). `context` is whatever the host renders the area for (e.g. `{ user }`) and is handed to the
+ * filter listeners. Same return shape as `useAsyncData`.
+ */
+export declare function useTabs(area: string, context?: MaybeRefOrGetter<Record<string, unknown> | undefined>): import("nuxt/app").AsyncData<TabMeta[] | undefined, import("nuxt/app").NuxtError<unknown> | undefined>;

package/dist/runtime/app/composables/useTabs.js

@@ -0,0 +1,19 @@
+import { computed, toValue } from "vue";
+import { useAsyncData, useNuxtApp } from "#imports";
+import { tabs as registry } from "#widgets/tabs";
+import { sortWidgets } from "../../utils/sort.js";
+export function useTabs(area, context) {
+  const nuxtApp = useNuxtApp();
+  const i18n = nuxtApp.$i18n;
+  const locale = computed(() => i18n?.locale?.value);
+  return useAsyncData(`tabs:${area}`, async () => {
+    const tabs = sortWidgets(registry[area] ?? []).map(({ component: _component, label, labelKey, ...meta }) => ({
+      ...meta,
+      labelKey,
+      label: (labelKey && i18n?.te?.(labelKey) ? i18n.t?.(labelKey) : void 0) ?? label ?? meta.id
+    }));
+    const ctx = { area, tabs, context: toValue(context) };
+    await nuxtApp.callHook("tabs:filter", ctx);
+    return ctx.tabs;
+  }, { watch: [locale] });
+}

package/dist/runtime/app/composables/useWidgets.d.ts

@@ -0,0 +1,8 @@
+import { type MaybeRefOrGetter } from 'vue';
+import type { WidgetMeta } from '../../../types.js';
+/**
+ * The widgets registered for an area, ordered and passed through the `widgets:filter` hook, as plain data
+ * (the component itself is resolved by `<WidgetArea>`). `context` is whatever the host renders the area for
+ * (e.g. `{ user }`) and is handed to the filter listeners. Same return shape as `useAsyncData`.
+ */
+export declare function useWidgets(area: string, context?: MaybeRefOrGetter<Record<string, unknown> | undefined>): import("nuxt/app").AsyncData<WidgetMeta[] | undefined, import("nuxt/app").NuxtError<unknown> | undefined>;

package/dist/runtime/app/composables/useWidgets.js

@@ -0,0 +1,13 @@
+import { toValue } from "vue";
+import { useAsyncData, useNuxtApp } from "#imports";
+import { widgets as registry } from "#widgets/registry";
+import { sortWidgets } from "../../utils/sort.js";
+export function useWidgets(area, context) {
+  const nuxtApp = useNuxtApp();
+  return useAsyncData(`widgets:${area}`, async () => {
+    const widgets = sortWidgets((registry[area] ?? []).map(({ component: _component, ...meta }) => meta));
+    const ctx = { area, widgets, context: toValue(context) };
+    await nuxtApp.callHook("widgets:filter", ctx);
+    return ctx.widgets;
+  });
+}

package/dist/runtime/app/utils/components.d.ts

@@ -0,0 +1,3 @@
+import { type Component } from 'vue';
+/** The (lazily loaded) component of a registered widget. */
+export declare function getWidgetComponent(area: string, id: string): Component | undefined;

package/dist/runtime/app/utils/components.js

@@ -0,0 +1,12 @@
+import { defineAsyncComponent, markRaw } from "vue";
+import { widgets as registry } from "#widgets/registry";
+const cache = /* @__PURE__ */ new Map();
+export function getWidgetComponent(area, id) {
+  const key = `${area}::${id}`;
+  if (!cache.has(key)) {
+    const widget = (registry[area] ?? []).find((item) => item.id === id);
+    if (!widget) return void 0;
+    cache.set(key, markRaw(defineAsyncComponent(widget.component)));
+  }
+  return cache.get(key);
+}

package/dist/runtime/app/utils/tabs.d.ts

@@ -0,0 +1,3 @@
+import { type Component } from 'vue';
+/** The (lazily loaded) component of a registered tab. */
+export declare function getTabComponent(area: string, id: string): Component | undefined;

package/dist/runtime/app/utils/tabs.js

@@ -0,0 +1,13 @@
+import { defineAsyncComponent, markRaw } from "vue";
+import { tabs as registry } from "#widgets/tabs";
+const cache = /* @__PURE__ */ new Map();
+export function getTabComponent(area, id) {
+  const key = `${area}::${id}`;
+  if (!cache.has(key)) {
+    const tabs = registry[area] ?? [];
+    const tab = tabs.find((item) => item.id === id);
+    if (!tab) return void 0;
+    cache.set(key, markRaw(defineAsyncComponent(tab.component)));
+  }
+  return cache.get(key);
+}

package/dist/runtime/utils/index.d.ts

@@ -0,0 +1,4 @@
+export { extendWidgets, deriveWidgetId, sortWidgets } from './widget.js';
+export type { WidgetDefinition, RegisteredWidget } from './widget.js';
+export { extendTabs, deriveTabId } from './tab.js';
+export type { TabDefinition, RegisteredTab } from './tab.js';

package/dist/runtime/utils/index.js

@@ -0,0 +1,2 @@
+export { extendWidgets, deriveWidgetId, sortWidgets } from "./widget.js";
+export { extendTabs, deriveTabId } from "./tab.js";

package/dist/runtime/utils/sort.d.ts

@@ -0,0 +1,4 @@
+/** Lower `order` first; widgets without one last, keeping registration order. */
+export declare function sortWidgets<T extends {
+    order?: number;
+}>(widgets: T[]): T[];

package/dist/runtime/utils/sort.js

@@ -0,0 +1,8 @@
+export function sortWidgets(widgets) {
+  return [...widgets].sort((a, b) => {
+    if (a.order === void 0 && b.order === void 0) return 0;
+    if (a.order === void 0) return 1;
+    if (b.order === void 0) return -1;
+    return a.order - b.order;
+  });
+}

package/dist/runtime/utils/tab.d.ts

@@ -0,0 +1,24 @@
+import type { Nuxt } from '@nuxt/schema';
+import type { TabDefinition } from '../../types.js';
+export type { TabDefinition, RegisteredTab } from '../../types.js';
+/** Id for a tab without one: its component's file name, e.g. `Payments` for `.../Payments.vue`. */
+export declare function deriveTabId(tab: Pick<TabDefinition, 'id' | 'component'>): string;
+/**
+ * Build-time API for modules to contribute tabs to a named area, without the host wiring anything. Call it
+ * once during a module's own `setup()`; registration order between modules doesn't matter. Tabs are kept apart
+ * from widgets, so the same area name can hold both.
+ *
+ * ```ts
+ * import { extendTabs } from '@frigear-nu/widget/utils'
+ *
+ * extendTabs(nuxt, 'admin.users', {
+ *   component: resolver.resolve('./runtime/app/tabs/Payments.vue'),
+ *   labelKey: 'admin.tabs.payments',
+ *   label: 'Payments',
+ *   order: 20,
+ * })
+ * ```
+ *
+ * A tab registered again under the same `id` in an area replaces the earlier one.
+ */
+export declare function extendTabs(nuxt: Nuxt, area: string, tabs: TabDefinition | TabDefinition[]): void;

package/dist/runtime/utils/tab.js

@@ -0,0 +1,16 @@
+import { basename, extname } from "node:path";
+export function deriveTabId(tab) {
+  return tab.id ?? basename(tab.component, extname(tab.component));
+}
+export function extendTabs(nuxt, area, tabs) {
+  const normalized = (Array.isArray(tabs) ? tabs : [tabs]).map((tab) => ({ ...tab, id: deriveTabId(tab), area }));
+  nuxt.options.widgets ||= {};
+  const registry = nuxt.options.widgets._tabs ||= {};
+  const list = registry[area] ||= [];
+  for (const tab of normalized) {
+    const existing = list.findIndex((item) => item.id === tab.id);
+    if (existing === -1) list.push(tab);
+    else list[existing] = tab;
+  }
+  nuxt.callHook("tabs:extend", area, normalized);
+}

package/dist/runtime/utils/widget.d.ts

@@ -0,0 +1,24 @@
+import type { Nuxt } from '@nuxt/schema';
+import type { WidgetDefinition } from '../../types.js';
+import { sortWidgets } from './sort.js';
+export type { WidgetDefinition, RegisteredWidget } from '../../types.js';
+export { sortWidgets };
+/** Id for a widget without one: its component's file name, e.g. `NewMembers` for `.../NewMembers.vue`. */
+export declare function deriveWidgetId(widget: Pick<WidgetDefinition, 'id' | 'component'>): string;
+/**
+ * Build-time API for modules to contribute widgets to a named area, without the host wiring anything. Call it
+ * once during a module's own `setup()`; registration order between modules doesn't matter.
+ *
+ * ```ts
+ * import { extendWidgets } from '@frigear-nu/widget/utils'
+ *
+ * extendWidgets(nuxt, 'admin.dashboard', {
+ *   component: resolver.resolve('./runtime/app/widgets/NewMembers.vue'),
+ *   order: 10,
+ * })
+ * ```
+ *
+ * A widget registered again under the same `id` in an area replaces the earlier one, so a host can override a
+ * module's widget by registering its own after it.
+ */
+export declare function extendWidgets(nuxt: Nuxt, area: string, widgets: WidgetDefinition | WidgetDefinition[]): void;

package/dist/runtime/utils/widget.js

@@ -0,0 +1,18 @@
+import { basename, extname } from "node:path";
+import { sortWidgets } from "./sort.js";
+export { sortWidgets };
+export function deriveWidgetId(widget) {
+  return widget.id ?? basename(widget.component, extname(widget.component));
+}
+export function extendWidgets(nuxt, area, widgets) {
+  const normalized = (Array.isArray(widgets) ? widgets : [widgets]).map((widget) => ({ ...widget, id: deriveWidgetId(widget), area }));
+  nuxt.options.widgets ||= {};
+  const extensions = nuxt.options.widgets._extensions ||= {};
+  const list = extensions[area] ||= [];
+  for (const widget of normalized) {
+    const existing = list.findIndex((item) => item.id === widget.id);
+    if (existing === -1) list.push(widget);
+    else list[existing] = widget;
+  }
+  nuxt.callHook("widgets:extend", area, normalized);
+}

package/dist/types.d.mts

@@ -0,0 +1,3 @@
+export { default } from './module.mjs'
+
+export { type ModuleOptions, type RegisteredTab, type RegisteredWidget, type TabDefinition, type TabMeta, type WidgetDefinition, type WidgetMeta } from './module.mjs'

package/package.json

@@ -1,6 +1,70 @@
 {
   "name": "@frigear-nu/widget",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.0.1",
+  "description": "Named widget areas - modules contribute widgets (extendWidgets) and hosts render them with <WidgetArea>, with ordering and a filter hook for gating.",
+  "homepage": "https://docs.frigear.dev/modules/widget",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/frigear-nu/frigear-nu.git",
+    "directory": "packages/widget"
+  },
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/module.mjs",
+  "exports": {
+    ".": {
+      "types": "./dist/types.d.mts",
+      "import": "./dist/module.mjs",
+      "default": "./dist/module.mjs"
+    },
+    "./utils": {
+      "types": "./dist/runtime/utils/index.d.ts",
+      "import": "./dist/runtime/utils/index.js",
+      "default": "./dist/runtime/utils/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "workspaces": [
+    "playground"
+  ],
+  "dependencies": {
+    "@nuxt/kit": "^4.6.0",
+    "@frigear-nu/module-kit": "0.1.6"
+  },
+  "devDependencies": {
+    "@nuxt/devtools": "^3.4.2",
+    "@nuxt/eslint-config": "^1.17.0",
+    "@nuxt/module-builder": "^1.0.3",
+    "@nuxt/schema": "^4.6.0",
+    "@nuxt/test-utils": "^4.3.2",
+    "@types/node": "latest",
+    "changelogen": "^0.6.2",
+    "eslint": "^10.10.0",
+    "nuxt": "^4.6.1",
+    "typescript": "^6.0.3",
+    "vitest": "^5.0.1",
+    "vue-tsc": "^3.3.11"
+  },
+  "scripts": {
+    "postinstall": "nuxt-module-build build --stub && nuxt prepare",
+    "build": "nuxt-module-build build",
+    "dev": "npm run dev:prepare && nuxt dev playground",
+    "dev:build": "nuxt build playground",
+    "dev:prepare": "nuxt-module-build build --stub && nuxt-module-build prepare && nuxt prepare playground",
+    "release": "npm run lint && npm run test && npm run prepack && changelogen --release && npm publish && git push --follow-tags",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
+    "test": "vitest run",
+    "test:watch": "vitest watch",
+    "test:types": "vue-tsc --noEmit && cd playground && vue-tsc --noEmit"
+  },
+  "typesVersions": {
+    "*": {
+      ".": [
+        "./dist/types.d.mts"
+      ]
+    }
+  }
 }