JobyKit.Manifest behaviour (JobyKit v0.1.0)

Copy Markdown View Source

Behaviour and DSL for declaring a JobyKit design-system manifest.

A host module uses this behaviour and registers its component inventory with the category/2 and component/3 macros. At compile time, the callbacks entries/0, by_category/0, categories/0, category_label/1, category_description/1, and fetch/2 are generated automatically.

Example

defmodule MyAppWeb.DesignManifest do
  use JobyKit.Manifest

  category :core,
    label: "Core wrappers",
    description: "One Bardo wrapper per daisyUI primitive."

  category :composite,
    label: "Generic composites",
    description: "Multi-primitive patterns reused across domains."

  component MyAppWeb.CoreComponents, :button,
    category: :core,
    daisy_basis: "btn",
    summary: "Text button family.",
    preview: &MyAppWeb.DesignPreviews.button/1

  component MyAppWeb.UIComponents, :listing_card,
    category: :composite,
    summary: "Navigable directory entry.",
    preview: &MyAppWeb.DesignPreviews.listing_card/1
end

Entry shape

Each entry returned by entries/0 is a map with these keys:

  • :module — the module the component is defined in
  • :function — the component function name
  • :category — :core, :composite, :domain, or any custom atom
  • :label — human-readable label
  • :daisy_basis — daisy class(es) the wrapper composes (or nil)
  • :summary — one-line description
  • :anchor — page anchor for cross-linking (or nil)
  • :preview — optional 1-arity function returning HEEX
  • :attrs — list of attr maps introspected from the component
  • :slots — list of slot maps introspected from the component
  • :line — source line of the component definition (or nil)
  • :data_component — the canonical "Module.function" string for the data-component attribute on the rendered element
  • :source — relative source path (or nil)

Summary

Types

attr_meta()
category_spec()
entry()
slot_meta()

Callbacks

by_category()
categories()
category_description(atom)
category_label(atom)
entries()
fetch(module, atom)

Functions

category(name, opts)

Register a category. Pass :label (human-readable) and :description (one-line) in opts.

component(module, function, opts)

Register a component.

enrich(component_registrations)

Enrich raw component registrations with introspected attrs/slots/source.

Types

attr_meta()

@type attr_meta() :: %{
  name: String.t(),
  type: String.t(),
  required: boolean(),
  default: term() | nil,
  values: [String.t()] | nil,
  doc: String.t() | nil
}

category_spec()

@type category_spec() :: {atom(), keyword()}

entry()

@type entry() :: %{
  module: module(),
  function: atom(),
  category: atom(),
  label: String.t(),
  daisy_basis: String.t() | nil,
  summary: String.t() | nil,
  anchor: String.t() | nil,
  preview: (map() -> Phoenix.LiveView.Rendered.t()) | nil,
  attrs: [attr_meta()],
  slots: [slot_meta()],
  line: integer() | nil,
  data_component: String.t(),
  source: String.t() | nil
}

slot_meta()

@type slot_meta() :: %{name: String.t(), required: boolean(), doc: String.t() | nil}

Callbacks

by_category()

@callback by_category() :: [{atom(), [entry()]}]

categories()

@callback categories() :: [atom()]

category_description(atom)

@callback category_description(atom()) :: String.t()

category_label(atom)

@callback category_label(atom()) :: String.t()

entries()

@callback entries() :: [entry()]

fetch(module, atom)

@callback fetch(module(), atom()) :: entry() | nil

Functions

category(name, opts)

(macro)

Register a category. Pass :label (human-readable) and :description (one-line) in opts.

category :core,
  label: "Core wrappers",
  description: "One wrapper per daisyUI primitive."

component(module, function, opts)

(macro)

Register a component.

Options

  • :category — required atom matching one of the declared categories
  • :label — defaults to the function name capitalized
  • :daisy_basis — daisy class(es) the wrapper composes
  • :summary — one-line description
  • :anchor — page anchor (defaults to nil; the page derives one)
  • :preview — optional 1-arity function returning HEEX

enrich(component_registrations)

Enrich raw component registrations with introspected attrs/slots/source.

Called at runtime by the generated entries/0 callback. Applied to each {module, function, opts} registration in declaration order.