@inglorious/web 2.0.0

package/src/router.js

@@ -0,0 +1,268 @@
+const SKIP_FULL_MATCH_GROUP = 1 // .match() result at index 0 is the full string
+const REMOVE_COLON_PREFIX = 1
+
+/**
+ * @typedef {Object} RouterEntity
+ * @property {string} id - The unique identifier for the router entity.
+ * @property {Object.<string, string>} routes - A map of URL patterns to entity types.
+ * @property {string} [path] - The current URL path.
+ * @property {string} [route] - The entity type for the current route.
+ * @property {Object.<string, string>} [params] - The parameters extracted from the URL.
+ * @property {Object.<string, string>} [query] - The query parameters from the URL.
+ * @property {string} [hash] - The URL hash.
+ */
+
+/**
+ * A client-side router type for an entity-based system. It handles URL changes,
+ * link interception, and history management (pushState, replaceState, popstate).
+ * @type {import('@inglorious/engine/types/type.js').Type}
+ */
+export const router = {
+  /**
+   * Initializes the router. It handles the initial route, sets up a `popstate`
+   * listener for browser navigation, and intercepts clicks on local `<a>` links.
+   * @param {RouterEntity} entity - The router entity.
+   * @param {*} payload - The message payload (unused).
+   * @param {import('../types/router.js').RouterApi} api - The router API.
+   */
+  init(entity, payload, api) {
+    // Handle initial route
+    const initialPath = window.location.pathname
+    const route = findRoute(entity.routes, initialPath)
+
+    if (route) {
+      entity.path = route.path
+      entity.route = route.entityType
+      entity.params = route.params
+
+      const query = Object.fromEntries(
+        new URLSearchParams(window.location.search),
+      )
+      entity.query = query
+      entity.hash = window.location.hash
+    }
+
+    const id = entity.id
+    // Listen for browser back/forward
+    window.addEventListener("popstate", () => {
+      const path = window.location.pathname
+      const { routes } = api.getEntity(id)
+      const route = findRoute(routes, path)
+
+      if (route) {
+        api.notify("routeSync", {
+          path: route.path,
+          entityType: route.entityType,
+          params: route.params,
+          query: Object.fromEntries(
+            new URLSearchParams(window.location.search),
+          ),
+          hash: window.location.hash,
+        })
+      }
+    })
+
+    // Intercept link clicks
+    document.addEventListener("click", (e) => {
+      // Find the closest <a> tag (handles clicks on children)
+      const link = e.target.closest("a")
+
+      if (!link) return
+
+      // Skip external links
+      if (link.target === "_blank") return
+      if (link.rel === "external") return
+      if (link.hasAttribute("data-external")) return
+
+      // Skip different origin links
+      if (link.origin !== window.location.origin) return
+
+      // Skip links with download attribute
+      if (link.hasAttribute("download")) return
+
+      // Skip mailto:, tel:, etc.
+      if (!["http:", "https:"].includes(link.protocol)) return
+
+      // Prevent default and use router
+      e.preventDefault()
+
+      const path = link.pathname + link.search + link.hash
+      api.notify("navigate", path)
+    })
+  },
+
+  /**
+   * Navigates to a new route, updating the browser's history and the router entity state.
+   * @param {RouterEntity} entity - The router entity.
+   * @param {string|number|import('../types/router.js').NavigatePayload} payload - The navigation payload.
+   * Can be a path string, a number for `history.go()`, or an object with navigation options.
+   * @param {string|number} payload.to - The destination path or history offset.
+   * @param {Object} [payload.params] - Route parameters to build the path from a pattern.
+   * @param {boolean} [payload.replace] - If true, uses `history.replaceState` instead of `pushState`.
+   * @param {Object} [payload.state] - Additional state to store in the browser's history.
+   * @param {import('../types/router.js').RouterApi} api - The router API.
+   */
+  navigate(entity, payload, api) {
+    if (["number", "string"].includes(typeof payload)) {
+      payload = { to: payload }
+    }
+
+    const { to, params, replace, state = {} } = payload
+
+    // Numeric navigation (back/forward)
+    if (typeof to === "number") {
+      history.go(to)
+      return
+    }
+
+    // Build final path
+    let path = to
+
+    // If params provided and "to" looks like a pattern, build the path
+    if (params && to.includes(":")) {
+      path = buildPath(to, params)
+    }
+
+    // If "to" is already a final path (like "/users/1"), use it directly
+    // The router will match it against patterns in entity.routes
+
+    const route = findRoute(entity.routes, path)
+
+    if (!route) {
+      console.warn(`No route matches path: ${path}`)
+      return
+    }
+
+    // Prevent navigation if the full path (including query/hash) is identical.
+    const currentFullPath =
+      entity.path + window.location.search + window.location.hash
+    if (path === currentFullPath) {
+      return
+    }
+
+    // Parse query string
+    const [pathname, search] = path.split("?")
+    const query = search ? Object.fromEntries(new URLSearchParams(search)) : {}
+
+    // Update entity with routing info
+    entity.path = pathname
+    entity.route = route.entityType
+    entity.params = route.params
+    entity.query = query
+    entity.hash = window.location.hash
+
+    // Prepare history state
+    const historyState = {
+      ...state,
+      route: route.entityType,
+      params: route.params,
+      query,
+      path: pathname,
+    }
+
+    // Navigate
+    const method = replace ? "replaceState" : "pushState"
+    history[method](historyState, "", path)
+
+    api.notify("routeChange", historyState)
+  },
+
+  /**
+   * Synchronizes the router entity's state with data from a routing event,
+   * typically triggered by a `popstate` event (browser back/forward).
+   * @param {RouterEntity} entity - The router entity to update.
+   * @param {import('../types/router.js').RouteSyncPayload} payload - The new route state.
+   */
+  routeSync(entity, payload) {
+    entity.path = payload.path
+    entity.route = payload.entityType
+    entity.params = payload.params
+    entity.query = payload.query
+    entity.hash = payload.hash
+  },
+}
+
+/**
+ * Builds a URL path by substituting parameters into a route pattern.
+ * Example: `buildPath("/users/:userId", { userId: "123" })` returns `"/users/123"`.
+ * @param {string} pattern - The route pattern (e.g., "/users/:userId").
+ * @param {Object.<string, string>} [params={}] - The parameters to substitute.
+ * @returns {string} The constructed path.
+ */
+function buildPath(pattern, params = {}) {
+  let path = pattern
+  Object.entries(params).forEach(([key, value]) => {
+    path = path.replace(`:${key}`, value)
+  })
+  return path
+}
+
+/**
+ * Finds a matching route configuration for a given URL path.
+ * It supports parameterized routes and a fallback "*" route.
+ * @param {Object.<string, string>} routes - The routes configuration map.
+ * @param {string} path - The URL path to match.
+ * @returns {{pattern: string, entityType: string, params: Object, path: string}|null}
+ * The matched route object or null if no match is found.
+ */
+function findRoute(routes, path) {
+  const [pathname] = path.split("?")
+  let fallbackRoute = null
+
+  for (const [pattern, entityType] of Object.entries(routes)) {
+    if (pattern === "*") {
+      fallbackRoute = { pattern, entityType, params: {}, path: pathname }
+      continue
+    }
+    const params = matchRoute(pattern, pathname)
+    if (params !== null) {
+      return { pattern, entityType, params, path: pathname }
+    }
+  }
+  return fallbackRoute
+}
+
+/**
+ * Matches a URL path against a route pattern and extracts any parameters.
+ * @param {string} pattern - The route pattern (e.g., "/users/:userId").
+ * @param {string} path - The URL path to match (e.g., "/users/123").
+ * @returns {Object.<string, string>|null} An object of extracted parameters,
+ * or null if the path does not match the pattern.
+ */
+function matchRoute(pattern, path) {
+  const paramNames = getParamNames(pattern)
+  const regex = patternToRegex(pattern)
+  const match = path.match(regex)
+
+  if (!match) return null
+
+  const params = {}
+  paramNames.forEach((name, i) => {
+    params[name] = match[i + SKIP_FULL_MATCH_GROUP]
+  })
+
+  return params
+}
+
+/**
+ * Parses a route pattern and extracts the names of its parameters.
+ * Example: `getParamNames("/users/:userId/posts/:postId")` returns `["userId", "postId"]`.
+ * @param {string} pattern - The route pattern.
+ * @returns {string[]} An array of parameter names.
+ */
+function getParamNames(pattern) {
+  const matches = pattern.match(/:(\w+)/g)
+  return matches ? matches.map((m) => m.slice(REMOVE_COLON_PREFIX)) : []
+}
+
+/**
+ * Converts a route pattern into a regular expression for matching URL paths.
+ * @param {string} pattern - The route pattern (e.g., "/users/:userId").
+ * @returns {RegExp} The corresponding regular expression.
+ */
+function patternToRegex(pattern) {
+  const regexPattern = pattern
+    .replace(/\//g, "\\/")
+    .replace(/:(\w+)/g, "([^\\/]+)")
+  return new RegExp(`^${regexPattern}$`)
+}

package/types/form.d.ts

@@ -0,0 +1,377 @@
+/**
+ * Represents the structure of form values, which can be a nested object.
+ */
+export type FormValues = Record<string, any>
+
+/**
+ * A recursive type that mirrors the structure of `T` (the form values),
+ * but with leaf nodes as `string | null`. Used for validation errors.
+ */
+export type FormErrors<T> = T extends (infer U)[]
+  ? FormErrors<U>[]
+  : T extends object
+    ? { [P in keyof T]?: FormErrors<T[P]> }
+    : string | null
+
+/**
+ * A recursive type that mirrors the structure of `T` (the form values),
+ * but with leaf nodes as `boolean`. Used for tracking touched fields.
+ */
+export type FormTouched<T> = T extends (infer U)[]
+  ? FormTouched<U>[]
+  : T extends object
+    ? { [P in keyof T]?: FormTouched<T[P]> }
+    : boolean
+
+/**
+ * Represents the state of a form entity. It is generic over the shape
+ * of the form's values.
+ */
+export interface FormEntity<T extends FormValues = FormValues> {
+  /** A unique identifier for the form entity. */
+  id: string | number
+  /** The initial values of the form, used for resetting. */
+  initialValues: T
+  /** The current values of the form fields. */
+  values: T
+  /** The current validation errors for the form fields. */
+  errors: FormErrors<T>
+  /** A map indicating if a field has been touched. */
+  touched: FormTouched<T>
+  /** A flag indicating if the form has any validation errors. */
+  isValid: boolean
+  /** A flag indicating if the form has not been touched. */
+  isPristine: boolean
+  /** A flag indicating if async validation is in progress. */
+  isValidating: boolean
+  /** A flag indicating if the form is currently being submitted. */
+  isSubmitting: boolean
+  /** An error message from form submission failure. */
+  submitError?: string | null
+}
+
+/**
+ * The payload for the `formFieldChange` event.
+ */
+export interface FormFieldChangePayload<T extends FormValues = FormValues> {
+  /** The ID of the target form entity. */
+  entityId: string | number
+  /** The dot-notation path to the field (e.g., 'user.name'). */
+  path: string
+  /** The new value of the field. */
+  value: any
+  /** An optional function to validate the field's value. */
+  validate?: (value: any) => string | null
+}
+
+/**
+ * The payload for the `formFieldBlur` event.
+ */
+export interface FormFieldBlurPayload {
+  /** The ID of the target form entity. */
+  entityId: string | number
+  /** The dot-notation path to the field (e.g., 'user.name'). */
+  path: string
+  /** An optional function to validate the field's value on blur. */
+  validate?: (value: any) => string | null
+}
+
+/**
+ * The payload for the `fieldArrayAppend` event.
+ */
+export interface FieldArrayAppendPayload {
+  /** The ID of the target form entity. */
+  entityId: string | number
+  /** The dot-notation path to the array field. */
+  path: string
+  /** The value to append to the array. */
+  value: any
+}
+
+/**
+ * The payload for the `fieldArrayRemove` event.
+ */
+export interface FieldArrayRemovePayload {
+  /** The ID of the target form entity. */
+  entityId: string | number
+  /** The dot-notation path to the array field. */
+  path: string
+  /** The index of the item to remove. */
+  index: number
+}
+
+/**
+ * The payload for the `fieldArrayInsert` event.
+ */
+export interface FieldArrayInsertPayload {
+  /** The ID of the target form entity. */
+  entityId: string | number
+  /** The dot-notation path to the array field. */
+  path: string
+  /** The index at which to insert the new item. */
+  index: number
+  /** The value to insert into the array. */
+  value: any
+}
+
+/**
+ * The payload for the `fieldArrayMove` event.
+ */
+export interface FieldArrayMovePayload {
+  /** The ID of the target form entity. */
+  entityId: string | number
+  /** The dot-notation path to the array field. */
+  path: string
+  /** The source index of the item to move. */
+  fromIndex: number
+  /** The destination index for the item. */
+  toIndex: number
+}
+
+/**
+ * The payload for the `formReset` event.
+ */
+export interface FormResetPayload {
+  /** The ID of the target form entity. */
+  entityId: string | number
+}
+
+/**
+ * The payload for the `formValidate` event (synchronous validation).
+ */
+export interface FormValidatePayload<T extends FormValues = FormValues> {
+  /** The ID of the target form entity. */
+  entityId: string | number
+  /**
+   * A function that validates the entire form's values and returns
+   * a complete error object.
+   */
+  validate: (values: T) => FormErrors<T>
+}
+
+/**
+ * The payload for the `formValidateAsync` event (asynchronous validation).
+ */
+export interface FormValidateAsyncPayload<T extends FormValues = FormValues> {
+  /** The ID of the target form entity. */
+  entityId: string | number
+  /**
+   * An async function that validates the entire form's values and returns
+   * a complete error object.
+   */
+  validate: (values: T) => Promise<FormErrors<T>>
+}
+
+/**
+ * The payload for the `formValidationComplete` event.
+ */
+export interface FormValidationCompletePayload<
+  T extends FormValues = FormValues,
+> {
+  /** The ID of the target form entity. */
+  entityId: string | number
+  /** The validation errors returned from async validation. */
+  errors: FormErrors<T>
+  /** Whether the form is valid (no errors). */
+  isValid: boolean
+}
+
+/**
+ * The payload for the `formValidationError` event.
+ */
+export interface FormValidationErrorPayload {
+  /** The ID of the target form entity. */
+  entityId: string | number
+  /** The error message from the failed validation. */
+  error: string
+}
+
+/**
+ * The form type implementation for the entity-based state manager.
+ */
+export declare const form: {
+  /**
+   * Initializes the form entity by resetting it to its initial state.
+   * @param entity The form entity.
+   */
+  init<T extends FormValues>(entity: FormEntity<T>): void
+
+  /**
+   * Resets the form entity when a 'create' event payload matches its ID.
+   * @param entity The form entity.
+   * @param entityId The entity ID from the create event, used to target a specific form.
+   */
+  create<T extends FormValues>(
+    entity: FormEntity<T>,
+    entityId: string | number,
+  ): void
+
+  /**
+   * Appends an item to a field array.
+   * @param entity The form entity.
+   * @param payload The append event payload.
+   */
+  fieldArrayAppend<T extends FormValues>(
+    entity: FormEntity<T>,
+    payload: FieldArrayAppendPayload,
+  ): void
+
+  /**
+   * Removes an item from a field array by index.
+   * @param entity The form entity.
+   * @param payload The remove event payload.
+   */
+  fieldArrayRemove<T extends FormValues>(
+    entity: FormEntity<T>,
+    payload: FieldArrayRemovePayload,
+  ): void
+
+  /**
+   * Inserts an item into a field array at a specific index.
+   * @param entity The form entity.
+   * @param payload The insert event payload.
+   */
+  fieldArrayInsert<T extends FormValues>(
+    entity: FormEntity<T>,
+    payload: FieldArrayInsertPayload,
+  ): void
+
+  /**
+   * Moves an item in a field array from one index to another.
+   * @param entity The form entity.
+   * @param payload The move event payload.
+   */
+  fieldArrayMove<T extends FormValues>(
+    entity: FormEntity<T>,
+    payload: FieldArrayMovePayload,
+  ): void
+
+  /**
+   * Handles a change in a form field's value and optionally validates it.
+   * @param entity The form entity.
+   * @param payload The change event payload.
+   */
+  fieldChange<T extends FormValues>(
+    entity: FormEntity<T>,
+    payload: FormFieldChangePayload<T>,
+  ): void
+
+  /**
+   * Handles the blur event for a form field, marking it as touched and optionally validating it.
+   * @param entity The form entity.
+   * @param payload The blur event payload.
+   */
+  fieldBlur<T extends FormValues>(
+    entity: FormEntity<T>,
+    payload: FormFieldBlurPayload,
+  ): void
+
+  /**
+   * Resets the form to its initial state.
+   * @param entity The form entity.
+   * @param payload The reset event payload.
+   */
+  reset<T extends FormValues>(
+    entity: FormEntity<T>,
+    payload: FormResetPayload,
+  ): void
+
+  /**
+   * Synchronously validates the entire form.
+   * @param entity The form entity.
+   * @param payload The validation event payload.
+   */
+  validate<T extends FormValues>(
+    entity: FormEntity<T>,
+    payload: FormValidatePayload<T>,
+  ): void
+
+  /**
+   * Asynchronously validates the entire form.
+   * Dispatches 'formValidationComplete' on success or 'formValidationError' on failure.
+   * @param entity The form entity.
+   * @param payload The async validation event payload.
+   * @param api The API object for notifying events.
+   */
+  validateAsync<T extends FormValues>(
+    entity: FormEntity<T>,
+    payload: FormValidateAsyncPayload<T>,
+    api: any,
+  ): Promise<void>
+
+  /**
+   * Handles the completion of async validation.
+   * @param entity The form entity.
+   * @param payload The validation completion event payload.
+   */
+  validationComplete<T extends FormValues>(
+    entity: FormEntity<T>,
+    payload: FormValidationCompletePayload<T>,
+  ): void
+
+  /**
+   * Handles validation errors from async validation.
+   * @param entity The form entity.
+   * @param payload The validation error event payload.
+   */
+  validationError<T extends FormValues>(
+    entity: FormEntity<T>,
+    payload: FormValidationErrorPayload,
+  ): void
+}
+
+/**
+ * Gets the value of a specific field in the form.
+ * @param form The form entity.
+ * @param path The path to the field (e.g., 'user.name').
+ * @param defaultValue An optional default value to return if the path does not exist.
+ */
+export declare function getFieldValue<T extends FormValues>(
+  form: FormEntity<T>,
+  path: string,
+  defaultValue?: any,
+): any
+
+/**
+ * Gets the error message for a specific field in the form.
+ * @param form The form entity.
+ * @param path The path to the field.
+ */
+export declare function getFieldError<T extends FormValues>(
+  form: FormEntity<T>,
+  path: string,
+): string | null
+
+/** Checks if a specific field has been touched by the user. */
+export declare function isFieldTouched<T extends FormValues>(
+  form: FormEntity<T>,
+  path: string,
+): boolean
+
+/**
+ * Checks if the form has any validation errors.
+ * @param errors The errors object from a form entity.
+ */
+export declare function hasErrors(errors: FormErrors<any>): boolean
+
+/** Initializes a nested metadata structure (for errors or touched state) based on a value structure. */
+export declare function initMetadata(value: any): any
+
+/** Resets the form to its initial state. */
+export declare function resetForm<T extends FormValues>(
+  form: FormEntity<T>,
+): void
+
+/** Sets the value of a specific field and marks it as touched. */
+export declare function setFieldValue<T extends FormValues>(
+  form: FormEntity<T>,
+  path: string,
+  value: any,
+): void
+
+/** Sets an error message for a specific field. */
+export declare function setFieldError<T extends FormValues>(
+  form: FormEntity<T>,
+  path: string,
+  error: string | null,
+): void

package/types/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./mount"
+export * from "./router"

package/types/mount.d.ts

@@ -0,0 +1,24 @@
+import type { TemplateResult } from "lit-html"
+import type { Store, Api as StoreApi } from "@inglorious/store"
+
+export type Api = StoreApi & {
+  /**
+   * Renders a single entity by its ID.
+   * @param id The ID of the entity to render.
+   * @returns The rendered template or null.
+   */
+  render: (id: string) => TemplateResult | null
+}
+
+/**
+ * Mounts a lit-html template to the DOM and subscribes to a store for re-rendering.
+ * @param store The application state store.
+ * @param renderFn The root render function that receives the API and returns a template.
+ * @param element The DOM element to mount the template to.
+ * @returns An unsubscribe function.
+ */
+export function mount(
+  store: Store,
+  renderFn: (api: Api) => TemplateResult | null,
+  element: HTMLElement | DocumentFragment,
+): () => void