@alfakit/core 0.0.0-stage → 0.1.0

package/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alfa Six Media and Management W.L.L.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,20 @@
-# Temporary Holding Version
+# @alfakit/core
 
-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.
+<p><picture><source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/alfasixbh/alfakit/main/art/alfasix/alfa-six-micro-white.svg"><img src="https://raw.githubusercontent.com/alfasixbh/alfakit/main/art/alfasix/alfa-six-micro-navy.svg" alt="" width="24" height="18" align="top"></picture> <sub>by <a href="https://alfasixbh.com">Alfa Six</a></sub></p>
+
+Framework-agnostic schema types and state management for AlfaKit renderers. You normally do not install this directly; it is a dependency of `@alfakit/react`, `@alfakit/vue` and `@alfakit/svelte`.
+
+AlfaKit is the frontend-agnostic admin panel builder for Laravel by [Alfa Six](https://alfasixbh.com). Panels, resources, forms, tables and actions are defined in PHP and rendered by this package.
+
+## Install
+
+```bash
+composer require alfasix/alfakit
+php artisan alfakit:install --adapter=react
+```
+
+The installer creates `resources/js/alfakit/app.*` and `resources/css/alfakit.css` and registers them with Vite. See the [documentation](https://alfakit.dev/docs) for custom components, pages and theming.
+
+## License
+
+MIT © Alfa Six

package/dist/actions.d.ts

@@ -0,0 +1,231 @@
+import { RecordKey, Size } from "./schema/common.js";
+import { NotificationSchema } from "./schema/notifications.js";
+import { ActionModalSchema, ActionSchema, AnyActionSchema } from "./schema/actions.js";
+import { Store } from "./store.js";
+import { FormStore } from "./form.js";
+//#region src/actions.d.ts
+export interface ActionContext {
+  /** Encrypted page context token. */
+  token: string;
+  /** `page`, `table`, `relationManager:Class`, `widget:Class`. */
+  component?: string;
+  record?: RecordKey | null;
+  /** Selected record keys for bulk actions. */
+  records?: RecordKey[];
+  /** "All filtered records" bulk selection. */
+  allRecords?: boolean;
+  arguments?: Record<string, unknown>;
+  /**
+   * Names of the actions whose modals this action sits in, outermost first (actions in a
+   * modal's footer). The server resolves the action by its path, `parent>child`.
+   */
+  parents?: string[];
+  /**
+   * Field actions (`component` = `field:{schema}::{key}`): the form the field belongs to.
+   * Its state is sent with the action and the refreshed form is merged back into it.
+   */
+  form?: FormStore;
+}
+export interface ExecuteOptions {
+  /** The current password, for actions with `requiresPasswordConfirmation()`. */
+  password?: string;
+  /**
+   * "Create & create another": run with the `another` argument and, when the server keeps
+   * the modal open, reload it with a fresh form (keeping `preserveFormData` fields).
+   */
+  createAnother?: boolean;
+}
+/** The argument `CreateAction` reads for "Create & create another". */
+export declare const CREATE_ANOTHER_ARGUMENT = "another";
+/**
+ * The state of the fresh form after "Create & create another": the server's defaults,
+ * plus the previous values of the fields `preserveFormData` names (all of them for `true`).
+ */
+export declare function createAnotherState(fresh: Record<string, unknown>, previous: Record<string, unknown>, preserve: boolean | string[] | undefined): Record<string, unknown>;
+export interface OpenModal {
+  action: ActionSchema;
+  context: ActionContext;
+  modal: ActionModalSchema;
+  /** Current form values of the modal form. */
+  errors: Record<string, string[]>;
+  processing: boolean;
+  /** Field actions: settles `runField()` with the action's result (undefined when closed). */
+  resolve?: (result: unknown) => void;
+  /**
+   * Bumped by `resetModal()` ("Create & create another"): the renderer focuses the form's
+   * `autofocus()` field again (`focusAutofocusField()`) once the fresh form rendered.
+   */
+  refocus?: number;
+}
+export interface ActionRunnerState {
+  /** Stack of open modals (nested modals are possible). */
+  modals: OpenModal[];
+  /** Name of the action currently loading its modal. */
+  loading: string | null;
+}
+export interface ActionRunnerOptions {
+  endpoints: {
+    action: string;
+    modal: string;
+  };
+  onError?: (error: unknown) => void;
+  /** Called after a successful run so the UI can e.g. clear a table selection. */
+  onSuccess?: (action: ActionSchema, context: ActionContext) => void;
+  /**
+   * Shows notifications that arrive in JSON responses (a modal that `mountUsing()`
+   * cancelled, field actions). Renderers can also set it with `setNotificationHandler()`.
+   */
+  onNotifications?: (notifications: NotificationSchema[]) => void;
+}
+/**
+ * Drives action buttons: plain links navigate, actions without a modal post straight to
+ * the server, and actions with a modal fetch the modal schema first.
+ */
+export declare class ActionRunner {
+  private readonly options;
+  readonly store: Store<ActionRunnerState>;
+  /** Runs in flight, so a double click or a repeated shortcut doesn't submit twice. */
+  private readonly running;
+  /** The form of each open modal (registered by the renderer), by modal path. */
+  private readonly modalForms;
+  constructor(options: ActionRunnerOptions);
+  get state(): ActionRunnerState;
+  /** Show notifications from JSON responses with this handler (e.g. the renderer's toasts). */
+  setNotificationHandler(handler: ((notifications: NotificationSchema[]) => void) | undefined): void;
+  private notify;
+  /** Point the runner at the current panel's endpoints (they change per tenant/panel). */
+  setEndpoints(endpoints: Partial<ActionRunnerOptions['endpoints']>): void;
+  /**
+   * The renderer registers the form of an open modal, so nested actions can send its state
+   * (`$mountedActions`, `getRawData()`) and `fillData()` can write into it. Returns the
+   * function that unregisters it.
+   */
+  registerModalForm(action: ActionSchema, context: ActionContext, form: FormStore): () => void;
+  /** The open modals of the actions a nested action sits in, outermost first. */
+  parentModals(context: ActionContext): Array<OpenModal | undefined>;
+  /**
+   * The form state of the modals a nested action sits in, outermost first (undefined when
+   * none of them has a form).
+   */
+  mountedData(context: ActionContext): Array<Record<string, unknown>> | undefined;
+  /** Entry point for a click on an action button. */
+  trigger(action: ActionSchema, context: ActionContext): Promise<void>;
+  /**
+   * Run a field action (opening its modal first, if it has one) and resolve with its
+   * result once it ran, or with undefined when the modal is closed without running it.
+   */
+  runField(action: ActionSchema, context: ActionContext): Promise<unknown>;
+  /**
+   * Run the action whose modal `button` sits in (a `makeModalSubmitAction()` button) with
+   * that modal's form state and the button's arguments.
+   */
+  submitParentModal(button: ActionSchema, context: ActionContext): void;
+  /**
+   * Close a modal the user dismissed (cancel, Escape, clicking away, close button). With
+   * `cancelParentActionsOnClose()` its parents close too.
+   */
+  cancelModal(name: string): void;
+  /** Close the modals `context` sits in: all of them, or up to and including `until`. */
+  closeParents(context: ActionContext, until: true | string): void;
+  openModal(action: ActionSchema, context: ActionContext, resolve?: (result: unknown) => void): Promise<void>;
+  private fetchModal;
+  /**
+   * After "Create & create another": load the modal again so its form starts from the
+   * server's defaults, keeping the `preserveFormData` fields from the values just sent.
+   */
+  resetModal(name: string, previous?: Record<string, unknown>): Promise<void>;
+  /** Whether this action is currently being submitted for this context. */
+  isRunning(action: ActionSchema, context: ActionContext): boolean;
+  closeModal(name?: string): void;
+  /** Submit the topmost modal (or run a modal-less action) through Inertia. */
+  execute(action: ActionSchema, context: ActionContext, data?: Record<string, unknown>, options?: ExecuteOptions): void;
+  /**
+   * Run an action and resolve with its JSON result (for callers that don't want an
+   * Inertia visit, e.g. a custom widget).
+   */
+  executeJson<T = unknown>(action: ActionSchema, context: ActionContext, data?: Record<string, unknown>): Promise<T>;
+  /**
+   * Run a field action as JSON with its form's state; merge the refreshed form from the
+   * response, settle the modal's `runField()` promise and close the modal.
+   */
+  executeField(action: ActionSchema, context: ActionContext, data?: Record<string, unknown>): Promise<unknown>;
+  private setProcessing;
+  private setErrors;
+}
+/**
+ * Whether an action button should bind its key bindings globally. Record actions repeat
+ * on every row, so a page-wide shortcut would run them once per record; they only bind
+ * when rendered outside a record (header, page and bulk actions).
+ */
+export declare function bindsKeyBindings(action: Pick<ActionSchema, 'keyBindings' | 'disabled'>, context: Pick<ActionContext, 'record'>): boolean;
+/** Button sizes every renderer's shadcn `Button` understands. */
+export type ActionButtonSize = 'xs' | 'sm' | 'default' | 'lg';
+/**
+ * The button size for an action: its own `size()` wins over the size the surrounding
+ * list asks for (`md` is the default button, `xl` the largest one).
+ */
+export declare function resolveActionSize(size: Size | null | undefined, fallback?: ActionButtonSize): ActionButtonSize;
+/** The square icon-only button that matches a button size. */
+export declare function iconButtonSize(size: ActionButtonSize): 'icon-xs' | 'icon-sm' | 'icon';
+export interface DropdownPlacement {
+  side: 'top' | 'right' | 'bottom' | 'left';
+  align: 'start' | 'center' | 'end';
+}
+/**
+ * Parse an ActionGroup `dropdownPlacement()` (`bottom-start`, `top-end`, `left`, …) into the
+ * side/align pair dropdown primitives take. Defaults to `bottom` / `end`.
+ */
+export declare function parseDropdownPlacement(placement: string | null | undefined): DropdownPlacement;
+/** Every action inside a group, nested groups flattened. */
+export declare function flattenActionGroup(actions: AnyActionSchema[]): ActionSchema[];
+/**
+ * Whether an open modal is hidden because a nested modal was opened from it. Nested modals
+ * hide their parents unless they opt into `overlayParentActions()`; a hidden parent shows
+ * again when the child closes.
+ */
+export declare function isModalHiddenByChild(modals: OpenModal[], index: number): boolean;
+/** Justify class keyword for modal footer buttons: `footerActionsAlignment`, else `alignment`. */
+export declare function modalFooterAlignment(modal: Pick<ActionModalSchema, 'alignment' | 'footerActionsAlignment'>): 'start' | 'center' | 'end' | 'between';
+/**
+ * The physical side a slide-over enters from: `end` (default) is the right edge in
+ * left-to-right documents and the left edge in right-to-left ones.
+ */
+export declare function slideOverSide(position: 'start' | 'end' | null | undefined, direction?: 'ltr' | 'rtl'): 'left' | 'right';
+/**
+ * Whether closing a modal has to ask first: its form changed and the modal has
+ * `unsavedChangesAlert` (the action's own setting or the panel's `unsavedChangesAlerts()`).
+ */
+export declare function shouldConfirmModalClose(modal: Pick<ActionModalSchema, 'unsavedChangesAlert'>, form: {
+  isDirty: boolean;
+} | null | undefined): boolean;
+/**
+ * Ask whether to close a modal with unsaved changes (`window.confirm`); true when it may
+ * close. Without changes (or the alert) it never asks.
+ */
+export declare function confirmModalClose(modal: Pick<ActionModalSchema, 'unsavedChangesAlert'>, form: {
+  isDirty: boolean;
+} | null | undefined, message: string): boolean;
+/**
+ * Warn before leaving the page (a reload, or an Inertia visit when `message` is given)
+ * while a modal form with `unsavedChangesAlert` has unsaved changes. Returns a function
+ * that removes the listeners.
+ */
+export declare function guardModalUnload(modal: Pick<ActionModalSchema, 'unsavedChangesAlert'>, form: {
+  isDirty: boolean;
+} | null | undefined, message?: string): () => void;
+/** The context of a user or tenant menu action: the page's token and the menu's component. */
+export declare function menuActionContext(token: string, menu: 'userMenu' | 'tenantMenu'): ActionContext;
+/**
+ * Split menu entries into their groups (`group` index, nested arrays in
+ * `userMenuItems()`), in order; renderers draw a separator between groups.
+ */
+export declare function groupMenuItems<T extends {
+  group?: number;
+}>(items: T[]): T[][];
+/**
+ * The action endpoint for a run. "All records" bulk actions carry the page's query string
+ * (filters, search, list tab), so the server selects exactly the records the table shows.
+ */
+export declare function actionEndpoint(endpoint: string, context: Pick<ActionContext, 'allRecords'>, search?: string): string;
+//#endregion
+//# sourceMappingURL=actions.d.ts.map

package/dist/actions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"actions.d.ts","names":[],"sources":["../src/actions.ts"],"mappings":";;;;;;iBA6BiB;;EAEf;;EAEA;EACA,SAAS;;EAET,UAAU;;EAEV;EACA,YAAY;;;;;EAKZ;;;;;EAKA,OAAO;;iBAGQ;;EAEf;;;;;EAKA;;;qBAIW;;;;;wBAMG,mBACd,OAAO,yBACP,UAAU,yBACV,2CACC;iBAiBc;EACf,QAAQ;EACR,SAAS;EACT,OAAO;;EAEP,QAAQ;EACR;;EAEA,WAAW;;;;;EAKX;;iBAGe;;EAEf,QAAQ;;EAER;;iBAGe;EACf;IAAa;IAAgB;;EAC7B,WAAW;;EAEX,aAAa,QAAQ,cAAc,SAAS;;;;;EAK5C,mBAAmB,eAAe;;;;;;qBAOvB;mBASkB;WARb,OAAO,MAAM;;mBAGZ;;mBAGA;EAEY,YAAA,SAAS;MAIlC,SAAS;;EAKb,uBACE,WAAW,eAAe;UAKpB;;EAOR,aAAa,WAAW,QAAQ;;;;;;EAShC,kBAAkB,QAAQ,cAAc,SAAS,eAAe,MAAM;;EAUtE,aAAa,SAAS,gBAAgB,MAAM;;;;;EAkB5C,YAAY,SAAS,gBAAgB,MAAM;;EAoBrC,QAAQ,QAAQ,cAAc,SAAS,gBAAgB;;;;;EA8DvD,SAAS,QAAQ,cAAc,SAAS,gBAAgB;;;;;EAkB9D,kBAAkB,QAAQ,cAAc,SAAS;;;;;EAqBjD,YAAY;;EAYZ,aAAa,SAAS,eAAe;EAY/B,UACJ,QAAQ,cACR,SAAS,eACT,WAAW,2BACV;UAwCK;;;;;EAgCF,WAAW,cAAc,WAAU,0BAA+B;;EAwCxE,UAAU,QAAQ,cAAc,SAAS;EAIzC,WAAW;;EAeX,QACE,QAAQ,cACR,SAAS,eACT,OAAM,yBACN,UAAS;;;;;EAmIL,YAAY,aAChB,QAAQ,cACR,SAAS,eACT,OAAM,0BACL,QAAQ;;;;;EAwCL,aACJ,QAAQ,cACR,SAAS,eACT,OAAM,0BACL;UAgFK;UAWA;;;;;;;wBAqBM,iBACd,QAAQ,KAAK,2CACb,SAAS,KAAK;;YAMJ;;;;;wBAMI,kBACd,MAAM,yBACN,WAAU,mBACT;;wBAiBa,eAAe,MAAM;iBAIpB;EACf;EACA;;;;;;wBAOc,uBAAuB,uCAAuC;;wBAa9D,mBAAmB,SAAS,oBAAoB;;;;;;wBAWhD,qBAAqB,QAAQ,aAAa;;wBAqB1C,qBACd,OAAO,KAAK;;;;;wBAkBE,cACd,8CACA;;;;;wBAiBc,wBACd,OAAO,KAAK,2CACZ;EAAQ;;;;;;wBASM,kBACd,OAAO,KAAK,2CACZ;EAAQ;sBACR;;;;;;wBAcc,iBACd,OAAO,KAAK,2CACZ;EAAQ;sBACR;;wBA8Bc,kBAAkB,eAAe,kCAAkC;;;;;wBAQnE,eAAe;EAAY;GAAkB,OAAO,MAAM;;;;;wBA4B1D,eACd,kBACA,SAAS,KAAK,8BACd"}