@pilotiq/pilotiq 0.1.0

package/src/schema/EmptyState.ts

@@ -0,0 +1,63 @@
+import { Element } from './Element.js'
+import type { Action } from '../actions/Action.js'
+
+/**
+ * Schema-level empty-state primitive — distinct from `Table.emptyState`
+ * (which is table-chrome). Use this when an entire page section, custom
+ * page, or dashboard zone has nothing to show. Drops into any layout
+ * the same way as `Heading` / `Text` / `Alert` do.
+ *
+ *   EmptyState.make('No reports yet')
+ *     .description('Create your first report to get started.')
+ *     .icon('file-text')
+ *     .footer([Action::make('create').url('/admin/reports/create')])
+ *
+ * v1 ships heading + description + icon + footer + `contained()`. Per-
+ * page-mode visibility, columnSpan etc. inherit from `Element`.
+ */
+export class EmptyState extends Element {
+  private _description?: string
+  private _icon?:        string
+  private _contained:    boolean = true
+
+  private constructor(private heading: string) {
+    super()
+  }
+
+  static make(heading: string): EmptyState {
+    return new EmptyState(heading)
+  }
+
+  description(d: string): this { this._description = d; return this }
+  icon(name: string):     this { this._icon        = name; return this }
+
+  /**
+   * Disable the default card-styled wrapper (background + border +
+   * padding) — useful when nesting inside another container that
+   * already brings its own chrome. Default `true` (contained).
+   */
+  contained(v = true): this { this._contained = v; return this }
+
+  /**
+   * Action buttons rendered below the description. Same shape as
+   * `Heading.actions(...)` — actions land on `_children` and serialize
+   * through the standard schema walker so `Action.evaluate(ctx)` for
+   * visibility / authorize fires unchanged.
+   */
+  footer(actions: Action[]): this {
+    this._children = actions
+    return this
+  }
+
+  override getType(): string { return 'emptyState' }
+
+  override toMeta() {
+    return {
+      type:      'emptyState' as const,
+      heading:   this.heading,
+      contained: this._contained,
+      ...(this._description ? { description: this._description } : {}),
+      ...(this._icon        ? { icon:        this._icon        } : {}),
+    }
+  }
+}

package/src/schema/Fieldset.ts

@@ -0,0 +1,43 @@
+import { Element } from './Element.js'
+
+/**
+ * Lightweight labeled container. Renders as `<fieldset><legend>` with a
+ * thin border + small horizontal padding. Lighter than `Section` — no
+ * description, no collapsible disclosure, no badge. Use when fields share
+ * a topic but the page already has section-level chrome.
+ *
+ * Optional `.columns(n)` produces a multi-column layout the same way
+ * `Section.columns()` does. Outside of forms, Fieldset still renders the
+ * border + legend; the renderer treats `<legend>` as a small heading
+ * regardless of context.
+ */
+export class Fieldset extends Element {
+  private _columns: 1 | 2 | 3 = 1
+
+  private constructor(private _label: string) {
+    super()
+  }
+
+  static make(label: string): Fieldset {
+    return new Fieldset(label)
+  }
+
+  /** Number of columns the fieldset's children are laid out in. Default 1. */
+  columns(n: 1 | 2 | 3): this { this._columns = n; return this }
+
+  /** Set the children. Any Element type is accepted. */
+  schema(elements: Element[]): this {
+    this._children = elements
+    return this
+  }
+
+  getType(): string { return 'fieldset' }
+
+  toMeta(): Record<string, unknown> {
+    return {
+      type: 'fieldset' as const,
+      label: this._label,
+      columns: this._columns,
+    }
+  }
+}

package/src/schema/Grid.ts

@@ -0,0 +1,43 @@
+import { Element } from './Element.js'
+
+/**
+ * Layout container that arranges its children in a column grid. Lighter than
+ * `Section` — no title, no description, no collapsible disclosure. Use it
+ * for ad-hoc multi-column layouts (e.g. side-by-side fields without a
+ * surrounding form section).
+ *
+ * `columns` defaults to 2 and accepts any positive integer; the client
+ * renderer is expected to clamp to a sensible max.
+ */
+export class Grid extends Element {
+  private _columns = 2
+  private _gap?: number
+
+  private constructor() {
+    super()
+  }
+
+  static make(): Grid {
+    return new Grid()
+  }
+
+  columns(n: number): this { this._columns = n; return this }
+
+  /** Optional gap between cells (units interpreted by the client renderer). */
+  gap(n: number): this { this._gap = n; return this }
+
+  schema(elements: Element[]): this {
+    this._children = elements
+    return this
+  }
+
+  getType(): string { return 'grid' }
+
+  toMeta(): Record<string, unknown> {
+    return {
+      type: 'grid' as const,
+      columns: this._columns,
+      ...(this._gap !== undefined ? { gap: this._gap } : {}),
+    }
+  }
+}

package/src/schema/Group.ts

@@ -0,0 +1,30 @@
+import { Element } from './Element.js'
+
+/**
+ * Chrome-less container. Renders its children in a plain `<div>` with no
+ * border, heading, padding, or background. Useful when you need a logical
+ * grouping for visibility (`Group.make().visible(({ $get }) => …)`) or for
+ * `_layout.columnSpan` on a parent grid without imposing visual chrome.
+ *
+ * Inherits `visible / hidden / columnSpan / columnStart / columnOrder`
+ * from `Element` (Plan #8). No own state apart from children.
+ */
+export class Group extends Element {
+  private constructor() { super() }
+
+  static make(): Group {
+    return new Group()
+  }
+
+  /** Set the children. Any Element type is accepted. */
+  schema(elements: Element[]): this {
+    this._children = elements
+    return this
+  }
+
+  getType(): string { return 'group' }
+
+  toMeta(): Record<string, unknown> {
+    return { type: 'group' as const }
+  }
+}

package/src/schema/Heading.ts

@@ -0,0 +1,39 @@
+import { Element } from './Element.js'
+import type { Action } from '../actions/Action.js'
+
+export class Heading extends Element {
+  private _level: 1 | 2 | 3 = 1
+  private _description?: string
+
+  private constructor(private content: string) {
+    super()
+  }
+
+  static make(content: string): Heading {
+    return new Heading(content)
+  }
+
+  level(l: 1 | 2 | 3): this { this._level = l; return this }
+  description(d: string): this { this._description = d; return this }
+
+  /**
+   * Attach action buttons that render aligned to the right of the
+   * heading text — admin-style page header. The renderer lays the
+   * heading + actions out as a flex row.
+   */
+  actions(actions: Action[]): this {
+    this._children = actions
+    return this
+  }
+
+  getType(): string { return 'heading' }
+
+  toMeta() {
+    return {
+      type: 'heading' as const,
+      content: this.content,
+      level: this._level,
+      ...(this._description ? { description: this._description } : {}),
+    }
+  }
+}

package/src/schema/Html.ts

@@ -0,0 +1,67 @@
+import { Element } from './Element.js'
+import type { MarkdownProseSize } from './Markdown.js'
+import { sanitizeHtml, type SanitizeConfig } from './sanitize.js'
+
+/**
+ * Display prime — renders a raw HTML string inline in a schema. Use when
+ * the source is already HTML (e.g. legacy CMS column, server-rendered
+ * template fragment). For Markdown source reach for `Markdown` instead.
+ *
+ * **Sanitized by default** against a prose-friendly allowlist (matches
+ * Filament v5's default-secure posture) — `<script>` / `<iframe>` /
+ * `javascript:` URLs / inline event handlers are stripped before the wire
+ * shape ships. Opt out with `.allowRaw()` (only when the source is fully
+ * admin-trusted AND already sanitized upstream) or widen the allowlist
+ * with `.sanitize({ allowedTags: [...] })`.
+ *
+ * @example
+ * Html.make('<p>Welcome to <strong>pilotiq</strong>.</p>').prose()
+ */
+export class Html extends Element {
+  private _prose = true
+  private _size?: MarkdownProseSize
+  private _sanitize: boolean | SanitizeConfig = true
+
+  private constructor(private html: string) {
+    super()
+  }
+
+  static make(html: string): Html {
+    return new Html(html)
+  }
+
+  /** Wrap output in a `prose` Tailwind Typography container. Default `true`. */
+  prose(v = true): this { this._prose = v; return this }
+
+  /** Tailwind Typography size — `prose-sm` / `prose-base` / `prose-lg`. */
+  size(s: MarkdownProseSize): this { this._size = s; return this }
+
+  /**
+   * Sanitization control. Default `true` — runs the source through the
+   * `DEFAULT_SANITIZE_CONFIG` allowlist before the wire shape ships. Pass
+   * `false` to disable (use `.allowRaw()` for the same effect with a
+   * clearer intent at the call site). Pass a `sanitize-html` config
+   * object to widen the allowlist.
+   */
+  sanitize(v: boolean | SanitizeConfig = true): this {
+    this._sanitize = v
+    return this
+  }
+
+  /** Sugar — opt out of the default-secure sanitizer entirely. */
+  allowRaw(): this { this._sanitize = false; return this }
+
+  getType(): string { return 'html' }
+
+  toMeta() {
+    const html = this._sanitize === false
+      ? this.html
+      : sanitizeHtml(this.html, this._sanitize === true ? undefined : this._sanitize)
+    return {
+      type:  'html' as const,
+      html,
+      prose: this._prose,
+      ...(this._size ? { size: this._size } : {}),
+    }
+  }
+}

package/src/schema/Icon.ts

@@ -0,0 +1,54 @@
+import { Element } from './Element.js'
+
+export type IconColor =
+  | 'default'
+  | 'muted'
+  | 'primary'
+  | 'destructive'
+  | 'success'
+  | 'warning'
+  | 'info'
+
+/**
+ * Display prime — renders an icon inline in a schema. Resolves through
+ * the user-extensible icon registry (`registerIcons({ name: Component })`),
+ * so the value is a kebab-case string. For component-typed icons used
+ * by Resource/Page/Global statics, see `IconValue` in `@pilotiq/pilotiq/icons`.
+ *
+ * @example
+ * Icon.make('check-circle').size(20).color('success')
+ */
+export class Icon extends Element {
+  private _size:  number    = 16
+  private _color: IconColor = 'default'
+  private _label?: string
+
+  private constructor(private name: string) {
+    super()
+  }
+
+  static make(name: string): Icon {
+    return new Icon(name)
+  }
+
+  /** Pixel size — drives both width and height. Default 16. */
+  size(px: number): this { this._size = px; return this }
+
+  color(c: IconColor): this { this._color = c; return this }
+
+  /** Accessible label. When set, the rendered icon gets `aria-label`;
+   *  otherwise it's `aria-hidden`. */
+  label(text: string): this { this._label = text; return this }
+
+  getType(): string { return 'icon' }
+
+  toMeta() {
+    return {
+      type:  'icon' as const,
+      name:  this.name,
+      size:  this._size,
+      color: this._color,
+      ...(this._label ? { label: this._label } : {}),
+    }
+  }
+}

package/src/schema/Image.ts

@@ -0,0 +1,57 @@
+import { Element } from './Element.js'
+
+export type ImageShape = 'square' | 'rounded' | 'circle'
+
+/**
+ * Display prime — renders an `<img>` inline in a schema. Use for inline
+ * thumbnails, avatars, brand marks, or detail-page hero shots; for
+ * table-cell images reach for `ImageColumn` instead.
+ *
+ * @example
+ * Image.make('https://cdn.example.com/avatar.png').alt('Avatar').size(64).circle()
+ */
+export class Image extends Element {
+  private _alt    = ''
+  private _width?:  number
+  private _height?: number
+  private _shape:  ImageShape = 'square'
+
+  private constructor(private url: string) {
+    super()
+  }
+
+  static make(url: string): Image {
+    return new Image(url)
+  }
+
+  alt(text: string): this { this._alt = text; return this }
+
+  /** Width in pixels. */
+  width(px: number): this { this._width = px; return this }
+
+  /** Height in pixels. */
+  height(px: number): this { this._height = px; return this }
+
+  /** Sugar for square width + height. */
+  size(px: number): this {
+    this._width = px
+    this._height = px
+    return this
+  }
+
+  rounded(): this { this._shape = 'rounded'; return this }
+  circle(): this  { this._shape = 'circle';  return this }
+
+  getType(): string { return 'image' }
+
+  toMeta() {
+    return {
+      type: 'image' as const,
+      url:  this.url,
+      alt:  this._alt,
+      shape: this._shape,
+      ...(this._width  !== undefined ? { width:  this._width  } : {}),
+      ...(this._height !== undefined ? { height: this._height } : {}),
+    }
+  }
+}

package/src/schema/LinkTag.ts

@@ -0,0 +1,41 @@
+import { Element } from './Element.js'
+
+/**
+ * Head-safe element — emits a `<link>` tag inside the panel's `<head>`.
+ * Use for canonical URLs, favicons, manifest hints, preload directives,
+ * and stylesheet imports (prefer `StyleTag` for inline CSS).
+ *
+ * @example
+ *   Pilotiq.renderHook('panels::head.start', () => [
+ *     LinkTag.make({ rel: 'icon', href: '/favicon.svg', type: 'image/svg+xml' }),
+ *     LinkTag.make({ rel: 'canonical', href: 'https://app.example.com' }),
+ *   ])
+ */
+export interface LinkTagAttrs {
+  rel:             string
+  href?:           string
+  /** Maps to the HTML `type` attribute (e.g. `image/svg+xml`, `text/css`).
+   *  Renamed from `type` because `type` is the wire-shape discriminator. */
+  mimeType?:       string
+  media?:          string
+  sizes?:          string
+  as?:             string
+  integrity?:      string
+  crossOrigin?:    'anonymous' | 'use-credentials' | ''
+  referrerPolicy?: string
+  hrefLang?:       string
+}
+
+export class LinkTag extends Element {
+  private constructor(private attrs: LinkTagAttrs) { super() }
+
+  static make(attrs: LinkTagAttrs): LinkTag {
+    return new LinkTag(attrs)
+  }
+
+  getType(): string { return 'link' }
+
+  toMeta() {
+    return { ...this.attrs, type: 'link' as const }
+  }
+}

package/src/schema/Markdown.ts

@@ -0,0 +1,85 @@
+import { marked } from 'marked'
+import { Element } from './Element.js'
+import { sanitizeHtml, type SanitizeConfig } from './sanitize.js'
+
+export type MarkdownProseSize = 'sm' | 'base' | 'lg'
+
+/**
+ * Display prime — renders read-only Markdown source. Server-side conversion
+ * via `marked` (already a dep), client receives finished HTML — no FOUC,
+ * no extra parser shipped to display-only pages.
+ *
+ * Read-only counterpart of `MarkdownField`. For raw HTML strings reach for
+ * `Html` instead.
+ *
+ * **Sanitized by default** against a prose-friendly allowlist (matches
+ * Filament v5's default-secure posture) — `<script>` / `<iframe>` /
+ * `javascript:` URLs / inline event handlers are stripped before the wire
+ * shape ships. Opt out with `.allowRaw()` (admin-trusted source AND
+ * reader) or widen the allowlist with `.sanitize({ allowedTags: [...] })`.
+ *
+ * @example
+ * Markdown.make('# Welcome\n\nThanks for **trying** pilotiq.').prose()
+ */
+export class Markdown extends Element {
+  private _gfm    = true
+  private _breaks = false
+  private _prose  = true
+  private _size?:  MarkdownProseSize
+  private _sanitize: boolean | SanitizeConfig = true
+
+  private constructor(private source: string) {
+    super()
+  }
+
+  static make(source: string): Markdown {
+    return new Markdown(source)
+  }
+
+  /** GitHub-flavored markdown. Default `true`. */
+  gfm(v = true): this { this._gfm = v; return this }
+
+  /** Convert single `\n` line breaks to `<br>`. Default `false`. */
+  breaks(v = true): this { this._breaks = v; return this }
+
+  /** Wrap output in a `prose` Tailwind Typography container. Default `true`.
+   *  Pass `false` to render bare HTML without typographic styling. */
+  prose(v = true): this { this._prose = v; return this }
+
+  /** Tailwind Typography size — `prose-sm` / `prose-base` / `prose-lg`. */
+  size(s: MarkdownProseSize): this { this._size = s; return this }
+
+  /**
+   * Sanitization control. Default `true` — runs the converted HTML through
+   * the `DEFAULT_SANITIZE_CONFIG` allowlist before the wire shape ships.
+   * Pass `false` to disable (use `.allowRaw()` for the same effect with a
+   * clearer intent at the call site). Pass a `sanitize-html` config object
+   * to widen the allowlist.
+   */
+  sanitize(v: boolean | SanitizeConfig = true): this {
+    this._sanitize = v
+    return this
+  }
+
+  /** Sugar — opt out of the default-secure sanitizer entirely. */
+  allowRaw(): this { this._sanitize = false; return this }
+
+  getType(): string { return 'markdown' }
+
+  toMeta() {
+    const html = marked.parse(this.source, {
+      gfm:    this._gfm,
+      breaks: this._breaks,
+      async:  false,
+    }) as string
+    const finalHtml = this._sanitize === false
+      ? html
+      : sanitizeHtml(html, this._sanitize === true ? undefined : this._sanitize)
+    return {
+      type:  'markdown' as const,
+      html:  finalHtml,
+      prose: this._prose,
+      ...(this._size ? { size: this._size } : {}),
+    }
+  }
+}

package/src/schema/MetaTag.ts

@@ -0,0 +1,41 @@
+import { Element } from './Element.js'
+
+/**
+ * Head-safe element — emits a `<meta>` tag inside the panel's `<head>`.
+ *
+ * Returned from `Pilotiq.renderHook('panels::head.start' | 'panels::head.end', …)`
+ * callbacks alongside `LinkTag` / `ScriptTag` / `StyleTag`. Schema-side
+ * `visible(ctx => …)` / `hidden(ctx => …)` predicates still apply, so a
+ * meta can be hidden behind feature flags or per-route logic just like
+ * any other Element.
+ *
+ * Either `name`, `property`, `httpEquiv`, or `charset` must be set —
+ * silently skipped at render-time if all four are absent.
+ *
+ * @example
+ *   Pilotiq.renderHook('panels::head.end', () => [
+ *     MetaTag.make({ property: 'og:image', content: 'https://…/og.png' }),
+ *     MetaTag.make({ name: 'csrf-token', content: req.csrfToken }),
+ *   ])
+ */
+export interface MetaTagAttrs {
+  name?:      string
+  property?:  string
+  httpEquiv?: string
+  charset?:   string
+  content?:   string
+}
+
+export class MetaTag extends Element {
+  private constructor(private attrs: MetaTagAttrs) { super() }
+
+  static make(attrs: MetaTagAttrs): MetaTag {
+    return new MetaTag(attrs)
+  }
+
+  getType(): string { return 'meta' }
+
+  toMeta() {
+    return { type: 'meta' as const, ...this.attrs }
+  }
+}

package/src/schema/RelationTabs.ts

@@ -0,0 +1,71 @@
+import { Element } from './Element.js'
+import { serializeIcon, type SerializedIcon, type IconValue } from '../icons/types.js'
+
+/**
+ * A single tab inside a `RelationTabs` strip — a labeled link to a
+ * sibling URL (the parent's Edit page, or one of the relation manager
+ * URLs). The renderer styles `active === true` differently and renders
+ * `url` as a plain `<a href>` so cmd-click + new-tab still work.
+ */
+export interface RelationTabMeta {
+  key:    string
+  label:  string
+  url:    string
+  active: boolean
+  icon?:  SerializedIcon
+}
+
+/**
+ * Plan #11 — navigation strip that ties a parent record's Edit/View
+ * page to its relation manager pages. Shown:
+ *   - on a Resource Edit/View page when `R.relations().length > 0`
+ *   - on every relation-list / -create / -edit page (so users can
+ *     jump back to the parent record or sideways to a sibling
+ *     manager without leaving the parent context)
+ *
+ * Not user-authored. The page-data builders construct it via
+ * `RelationTabs.make(tabs)` after computing each tab's URL and
+ * active-tab state.
+ */
+export class RelationTabs extends Element {
+  private constructor(private readonly _tabs: RelationTabMeta[]) {
+    super()
+  }
+
+  static make(tabs: RelationTabMeta[]): RelationTabs {
+    return new RelationTabs(tabs)
+  }
+
+  getType(): string { return 'relation-tabs' }
+
+  toMeta() {
+    return {
+      type: 'relation-tabs' as const,
+      tabs: this._tabs,
+    }
+  }
+}
+
+/** Convenience: build a tab descriptor with the icon serialized in
+ *  the same shape as Resource / Manager nav items. Owner-class name
+ *  threads through so component-typed icons resolve via the Vite
+ *  plugin's `_components.ts` manifest. */
+export function relationTab(opts: {
+  key:    string
+  label:  string
+  url:    string
+  active: boolean
+  icon?:  IconValue
+  iconOwner?: string
+}): RelationTabMeta {
+  const tab: RelationTabMeta = {
+    key:    opts.key,
+    label:  opts.label,
+    url:    opts.url,
+    active: opts.active,
+  }
+  if (opts.icon !== undefined) {
+    tab.icon = serializeIcon(opts.icon, opts.iconOwner ?? opts.key)
+  }
+  return tab
+}