@lowdefy/docs-content 0.0.0-experimental-20260710073520

package/content/concepts/menus.md

@@ -0,0 +1,144 @@
+# Menus
+
+> The menu items are filtered according to pages the user is authorized to see. This can be controlled by making pages public or private, or by assigning roles to authenticated users. See <a href = "/protected-pages-apis">protected pages and APIs</a> and <a href = "/roles">roles</a> for more on how to set this up.
+
+Menu objects describe links to pages, within the app or external. Menu lists are filtered to only show pages that the user is authorized to see as a result of public, private or role based access controlled (RBAC) configuration. Blocks such as [PageSiderMenu](/PageSiderMenu) render menu links. If no menu defined, a default menu is created, containing links to all pages defined in the app.
+
+By default blocks using a menu, like `PageSiderMenu`, will use the menu with `id: default`. This means that if you create a menu object with `id: default`, this will be used unless another menu is configured and referenced under the block properties, allowing for page specific menu configurations.
+
+More than one menu can be configured in an app. As an example, this can be used when two logically different sections in the app need different menus.
+
+The menu objects can be referenced by using the [`_menu`](/_menu) operator.
+
+The schema for a menu object is:
+
+- `id: string`: __Required__ - A identifier for the menu. If it is `default`, it will be used as default by blocks, like [PageHeaderMenu](/PageHeaderMenu), which display a menu.
+- `links: object[]`: An array of `MenuLink` or `MenuGroup` objects that form the links in the menu. `MenuGroups` can be two levels deep.
+
+The schema for a `MenuLink` is:
+- `id: string`: __Required__ - A identifier for the link unique to the menu.
+- `type: string`: __Required__ - The type should be `MenuLink`.
+- `pageId: string`: The id of the page to link to. Used as the menu item title if no title is provided.
+- `url: string`: An external url to link to.
+- `class: string | array | object`: CSS classes (including Tailwind utilities) for the item. Flat applies to the item wrapper; use an object with dot-prefixed slot keys (`.element`, `.icon`, `.label`) to target specific parts.
+- `style: object`: CSS styles for the item. Flat applies to the wrapper; use dot-prefixed slot keys (`.element`, `.icon`, `.label`) to target specific parts.
+-  `properties: object`: The properties of the menu link. These are:
+    - `title: string`: The title to display for the link.
+    - `icon: string | object`: The name of a [React Icon](https://react-icons.github.io/react-icons/search) or properties of an Icon block to use as the icon for the link.
+    - `danger: boolean`: Apply danger style (switches the item onto antd's `dangerItem*` token set).
+    - `disabled: boolean`: Disable the item — blocks clicks and applies a greyed style.
+    - `tooltip: string`: Tooltip text shown when the menu is collapsed.
+    - `extra: string`: Free-form right-aligned label on the item (e.g. `beta`, `soon`). For real keyboard shortcuts use `shortcut`, which both renders a kbd badge AND wires the key handler. When both are set, `shortcut` sits to the far right of `extra`.
+    - `shortcut: string`: Keyboard shortcut for this menu item. Renders a kbd badge floated to the far right of the item AND wires the key handler (fires `onSelect` when pressed). Use `mod` for Cmd/Ctrl. Supports sequences like `g s` and multi-key combos like `mod+shift+q`.
+
+The schema for a `MenuGroup` is:
+- `id: string`: __Required__ - A identifier for the group unique to the menu.
+- `type: string`: __Required__ - The type should be `MenuGroup`.
+- `class: string | array | object`: CSS classes for the group's title row. Use the `.popup` slot key (object form) to style the floating SubMenu popup.
+- `style: object`: CSS styles for the group's title row. Use dot-prefixed slot keys to target specific parts.
+-  `properties: object`: The properties of the menu group. These are:
+    - `title: string`: The title to display for the group.
+    - `icon: string | object`: The name of a [React Icon](https://react-icons.github.io/react-icons/search) or properties of an Icon block to use as the icon for the group.
+    - `disabled: boolean`: Disable the group — blocks expansion and applies a greyed style.
+    - `tooltip: string`: Tooltip text shown when the menu is collapsed.
+- `links: object[]`: An array of `MenuLink` or `MenuGroup` objects that should be grouped together in the group.
+
+The schema for a `MenuDivider` is:
+- `id: string`: __Required__ - A identifier for the divider unique to the menu.
+- `type: string`: __Required__ - The type should be `MenuDivider`.
+- `class: string | array | object`: CSS classes for the divider line.
+- `style: object`: CSS styles for the divider line.
+-  `properties: object`: The properties of the divider. These are:
+    - `dashed: boolean`: Render the divider as a dashed line.
+
+###### Menus example:
+```yaml
+lowdefy: LOWDEFY_VERSION
+menus:
+  - id: default
+    links:
+      - id: page1
+        type: MenuLink
+        pageId: page1
+        properties:
+          title: Page 1
+          icon: AiOutlineFile
+      - id: top-group
+        properties:
+          title: Group
+          icon: AiOutlineGroup
+        links:
+          - id: page2
+            type: MenuLink
+            pageId: page2 # pageId will be used as link title
+          - id: external
+            type: MenuLink
+            url: https://external.com
+            properties:
+              title: External site
+          - id: nested-group
+            type: MenuGroup
+            properties:
+              title: Nested Group
+            links:
+              - id: page3
+                type: MenuLink
+                pageId: page3
+                properties:
+                  title: Page 3
+  - id: page-1-and-3
+    links:
+      - id: page1
+        type: MenuLink
+        pageId: page1
+        properties:
+          title: Page 1
+          icon: AiOutlineFile
+      - id: page3
+        type: MenuLink
+        pageId: page3
+        properties:
+          title: Page 3
+          icon: AiOutlineControl
+```
+
+We can make use of [protected pages and APIs](/protected-pages-apis) and [roles](/roles) to filter the menu items according to the pages that the user has access to.
+
+###### lowdefy.yaml
+```yaml
+lowdefy: LOWDEFY_VERSION
+
+auth:
+  # ...
+  pages:
+    protected: true
+    public:
+      - login
+      - '404'
+    roles:
+      admin:
+        - page2
+        - page3
+      user:
+        - page1
+
+menus:
+  - id: default
+    links:
+      - id: page1
+        type: MenuLink
+        pageId: page1
+        properties:
+          title: Page 1
+          icon: AiOutlineFile
+      - id: page2
+        type: MenuLink
+        pageId: page2 # pageId will be used as link title
+      - id: page3
+        type: MenuLink
+        pageId: page3
+        properties:
+          title: Page 3
+  ```
+
+  In the example above, public users can only view the `login` and `404` pages, all other pages require the user to be logged in. If the authorized user had been given only the `user` role, they will only be able to see `page1`. In order to see `page2` and `page3`, the authorized user will need to have the `admin` role assigned to them. The menu will be filtered accordingly and will only contain the menu items that the user has access to.

package/content/concepts/module-authoring.md

@@ -0,0 +1,564 @@
+# Writing Modules
+
+This guide covers how to create, test, and publish Lowdefy modules.
+
+## Module Project Structure
+
+A module is a directory containing a `module.lowdefy.yaml` manifest and supporting config files:
+
+```
+my-module/
+├── module.lowdefy.yaml       # Module manifest (entry point)
+├── pages/
+│   ├── users-list.yaml
+│   ├── user-edit.yaml
+│   └── user-invite.yaml
+├── connections/
+│   └── users-db.yaml
+├── api/
+│   └── invite-user.yaml
+├── components/
+│   ├── user-avatar.yaml
+│   └── user-search.yaml
+└── menus.yaml
+```
+
+For monorepos with multiple modules:
+
+```
+my-modules/
+├── user-admin/
+│   ├── module.lowdefy.yaml
+│   ├── pages/
+│   └── connections/
+├── notifications/
+│   ├── module.lowdefy.yaml
+│   ├── pages/
+│   └── components/
+└── shared/                   # Shared files (not a module)
+    ├── page-layout.yaml
+    └── validate-email.yaml
+```
+
+Modules in a monorepo can reference shared files outside their own directory with `../`. See [Ref Path Resolution](#ref-path-resolution).
+
+### Ref Path Resolution
+
+`_ref` paths inside a module are relative to the module root (the directory containing `module.lowdefy.yaml`), not to the file doing the `_ref`. The same path works from any file in the module, regardless of nesting depth:
+
+```yaml
+# module root: my-module/
+# This ref works the same from:
+#   my-module/module.lowdefy.yaml
+#   my-module/pages/users-list.yaml
+#   my-module/pages/admin/users-edit.yaml
+header:
+  _ref: components/page-header.yaml   # always resolves to my-module/components/page-header.yaml
+```
+
+Use `../` only to reference files outside the module — typically shared files in a monorepo:
+
+```yaml
+# module root: my-modules/user-admin/
+# _ref resolves to my-modules/shared/page-layout.yaml
+layout:
+  _ref: ../shared/page-layout.yaml
+```
+
+The build prevents `../` from escaping the package root — the git repo root for local (`file:`) modules (falling back to the module directory itself if not in a git repo), or the fetched repo root for `github:` modules. Breaking out throws a config error.
+
+## How Modules Stay Scoped and Composable
+
+Three mechanisms keep modules working at scale. **Auto-scoping** prefixes every page, connection, API endpoint, notification, and menu item ID with the entry's `id`, so module authors write plain IDs and installing the same module twice under different entry IDs produces no collisions. **`_module.var`** lets any file in the module read the entry's vars at any depth, without the app threading values through nested `_ref`s. **Typed exports** declared in `exports:` mark which pages, components, endpoints, connections, and menus are public, so internal files stay internal and renaming one does not break consumers.
+
+## Writing module.lowdefy.yaml
+
+The manifest declares the module's interface and contents:
+
+```yaml
+name: User Admin
+description: User administration — list, edit, invite users
+
+vars:
+  roles:
+    type: array
+    required: true
+    description: List of available user roles
+  collection:
+    type: string
+    default: users
+    description: MongoDB collection name
+  components:
+    type: object
+    description: Component overrides (table_columns, form_fields)
+  request_stages:
+    type: object
+    description: Request pipeline stage overrides
+
+connections:
+  - _ref: connections/users-db.yaml
+
+pages:
+  - _ref: pages/users-list.yaml
+  - _ref: pages/user-edit.yaml
+  - _ref: pages/user-invite.yaml
+
+api:
+  - _ref: api/invite-user.yaml
+
+notifications:
+  - _ref: notifications/invite-user.yaml
+
+components:
+  - id: user-avatar
+    component:
+      _ref: components/user-avatar.yaml
+  - id: user-search
+    component:
+      _ref: components/user-search.yaml
+
+menus:
+  - _ref: menus.yaml
+
+# Default Lowdefy plugins (blocks-antd, blocks-basic, etc.) do not
+# need to be declared — only declare non-default plugins.
+plugins:
+  - name: "@lowdefy/blocks-aggrid"
+    version: "^4"
+
+secrets:
+  - name: MONGODB
+    description: MongoDB connection URI
+  - name: SENDGRID_API_KEY
+    description: SendGrid API key for sending invitations
+    required: false
+```
+
+## Declaring Vars
+
+The `vars` section declares what configuration the module accepts. Each variable can specify:
+- `type` — Expected type (`string`, `number`, `boolean`, `array`, `object`).
+- `required` — Whether the consuming app must provide this variable. Defaults to `false`.
+- `default` — Default value used when the app does not provide one.
+- `description` — Documentation for the variable's purpose.
+- `properties` — For `object` vars, declares nested keys with their own type, default, required, and description. Consumer values are merged at the property level — only overridden keys change.
+
+Defaults are expressions. They can be literals, or operator trees — `_ref`, `_module.var`, `_build.*`, or any combination. The build resolves a default lazily, only when `_module.var` reads the var and the consumer did not provide a value. Vars with `properties` merge at the property level: the consumer overrides only the keys they provide, and the rest resolve their own defaults independently.
+
+Unused vars are never read, so their defaults never resolve and their declared `type` is never checked.
+
+```yaml
+vars:
+  collection:
+    type: string
+    default: contacts
+  components:
+    type: object
+    properties:
+      table:
+        type: boolean
+        default: true
+      filter:
+        type: boolean
+        default: true
+```
+
+If the consumer provides `components: { filter: false }`, the effective value is `{ table: true, filter: false }`.
+
+### Dynamic Defaults
+
+Defaults are expressions. A `default:` value can be a literal, a `_ref` to a file, a `_module.var` reference to another var, or any `_build.*` tree. The build resolves a default on read — only when `_module.var` accesses the var and the consumer did not provide a value.
+
+The two most common patterns are loading a default from a file and deriving one var from another:
+
+```yaml
+vars:
+  table_columns:
+    default:
+      _ref: defaults/table-columns.yaml
+  page_title:
+    default:
+      _module.var: label_plural
+```
+
+`_ref` lets the module ship a structured default (a block tree, a column schema, a default request body) as its own file. `_module.var` inside a default turns one consumer-provided value into several — set `label_plural: "Users"` and `page_title` derives from it unless the consumer overrides it directly.
+
+Defaults scale up to full operator trees and namespace-level merging:
+
+```yaml
+vars:
+  show_title:
+    type: boolean
+    default: true
+
+  # Default built from another var
+  page_title:
+    type: string
+    default:
+      _build.if:
+        - _module.var: show_title
+        - 'Contact Form'
+        - null
+
+  # Namespace var — each property's default resolves on its own
+  components:
+    type: object
+    properties:
+      form_fields:
+        type: array
+        default:
+          _ref: components/form_contact.yaml
+      show_header:
+        type: boolean
+        default:
+          _module.var: show_title
+```
+
+When a consumer passes `components: { show_header: false }`, `show_header` keeps the consumer value and the build still resolves the `form_fields` default — property-level merging plus lazy resolution combine without any extra work from the author.
+
+A default that reads another var via `_module.var` triggers that var's resolution first. The build walks the dependency graph on demand, caching results per module entry. Circular `_module.var` graphs between defaults have no natural terminator — the build stack-overflows. Keep default graphs acyclic.
+
+## Using _module.var
+
+The [`_module.var`](/_module) operator reads module entry variables — it returns the consumer value when provided, or resolves the manifest default on read. It takes a string argument and works at any depth within module files, without threading vars through nested `_ref`s:
+
+```yaml
+# Any file in the module, at any nesting depth
+collection:
+  _module.var: collection
+
+# Nested path access (dot notation)
+show_filter:
+  _module.var: components.filter
+```
+
+`_var` continues to work for normal `_ref`-level vars (local composition between files within the module). `_module.var` is specifically for the vars passed by the app developer.
+
+## Using ID Operators
+
+Module authors use [`_module.pageId`](/_module), [`_module.connectionId`](/_module), [`_module.endpointId`](/_module), and [`_module.notificationId`](/_module) to reference sibling resources. These resolve to the fully scoped ID at build time:
+
+```yaml
+# Link to a sibling page
+- id: link_to_edit
+  type: Link
+  params:
+    pageId:
+      _module.pageId: user-edit
+
+# Reference a module connection
+connectionId:
+  _module.connectionId: users-db
+
+# Call a module API endpoint
+- id: call_invite
+  type: CallAPI
+  params:
+    endpointId:
+      _module.endpointId: invite-user
+```
+
+Use [`_module.id`](/_module) for the raw module entry ID:
+
+```yaml
+label:
+  _string.concat:
+    - _module.id: true
+    - " - User Admin"
+```
+
+## Exposing Components
+
+Components are reusable config fragments that consuming apps can `_ref` into any page. Declare them in the manifest:
+
+```yaml
+components:
+  - id: user-avatar
+    component:
+      _ref: components/user-avatar.yaml
+```
+
+Components can use both `_module.var` (module-level config) and `_var` (per-ref vars passed at the point of inclusion):
+
+```yaml
+# components/contact-selector.yaml
+id:
+  _var:
+    key: field_id
+    default: contact
+type: Selector
+properties:
+  label:
+    _module.var: contact_label
+  options:
+    _request: get-contacts.contacts
+```
+
+The consuming app includes it:
+
+```yaml
+blocks:
+  - _ref:
+      module: crm
+      component: contact-selector
+      vars:
+        field_id: primary_contact
+```
+
+## Declaring Dependencies
+
+When your module needs resources from another module — pages to link to, components to embed, APIs to call — declare those dependencies in `module.lowdefy.yaml`:
+
+```yaml
+dependencies:
+  - id: contacts
+    description: Contact management (selector component, detail pages)
+  - id: layout
+    description: Page layout components
+  - id: events
+    description: Audit event logging
+```
+
+Each dependency has an `id` (the abstract name you use in your module content) and a `description` (documents what kind of module is expected). The `id` is your choice — it's not tied to any specific entry name.
+
+## Declaring Exports
+
+Declare what your module exposes so the build can validate cross-module references:
+
+```yaml
+exports:
+  pages:
+    - id: company-list
+    - id: company-detail
+  components:
+    - id: company-selector
+      description: Dropdown selector for picking companies
+  menus:
+    - id: default
+  api:
+    - id: save-company
+```
+
+Omit empty sections. The build validates that cross-module references target declared exports.
+
+## Using Cross-Module References
+
+### Linking to Pages in Another Module
+
+Use the object form of `_module.pageId` with a `module` field:
+
+```yaml
+# Link to a page in the contacts dependency
+- id: view-contact
+  type: Link
+  params:
+    pageId:
+      _module.pageId:
+        id: contact-detail
+        module: contacts
+```
+
+The string form (`_module.pageId: company-detail`) continues to reference the current module's own pages.
+
+### Calling APIs in Another Module
+
+```yaml
+- id: log-event
+  type: CallAPI
+  params:
+    endpointId:
+      _module.endpointId:
+        id: log-event
+        module: events
+```
+
+### Embedding Components from Another Module
+
+Use `_ref: { module, component }` where `module` is the abstract dependency name:
+
+```yaml
+blocks:
+  - _ref:
+      module: contacts
+      component: contact-selector
+      vars:
+        field_id: primary_contact
+```
+
+The embedded component resolves in its source module's context. Its `_module.var` and `_module.*Id` operators read from the source module's entry — not yours. Per-ref `_var` works for customizing the component at the point of inclusion.
+
+### Including Menus from Another Module
+
+Use `_build.array.concat` to combine module and local links:
+
+```yaml
+links:
+  _build.array.concat:
+    - _ref:
+        module: contacts
+        menu: default
+    - _ref: menus/company-links.yaml
+```
+
+Cross-module `_ref` supports `component` and `menu` types only. Pages, connections, and APIs have dedicated ID operators.
+
+## Menu Export Convention
+
+Module menus should export only one level of links — flat MenuLink items, no nested MenuGroups. The app controls grouping. This keeps module menus composable: the app can wrap the links in any MenuGroup structure it needs.
+
+```yaml
+# menus.yaml — good: flat links only
+id: default
+links:
+  - id: users
+    type: MenuLink
+    pageId:
+      _module.pageId: users-list
+    properties:
+      title: Users
+      icon: AiOutlineUser
+  - id: invite
+    type: MenuLink
+    pageId:
+      _module.pageId: user-invite
+    properties:
+      title: Invite User
+      icon: AiOutlineUserAdd
+```
+
+The app wraps these in a MenuGroup:
+
+```yaml
+# lowdefy.yaml — app controls grouping
+menus:
+  - id: default
+    links:
+      - id: user-admin
+        type: MenuGroup
+        properties:
+          title: User Admin
+        links:
+          _ref:
+            module: user-admin
+            menu: default
+```
+
+## Data-Like Exports
+
+Components can export any config — not just UI blocks. Enum maps, config templates, and schema fragments all work through the same `components` mechanism:
+
+```yaml
+# In module.lowdefy.yaml
+vars:
+  event_types:
+    type: object
+    default: {}
+  change_stamp:
+    type: object
+    default:
+      timestamp:
+        _user: updated_at
+
+components:
+  # Enum map merged with app additions
+  - id: event_types
+    component:
+      _build.object.assign:
+        - _ref: ../shared/enums/event_types.yaml
+        - _module.var: event_types
+
+  # Config template with var override
+  - id: change_stamp
+    component:
+      _module.var: change_stamp
+```
+
+Consumers use the same `_ref: { module, component }` syntax. The `key` argument lets consumers extract nested values from the resolved content:
+
+```yaml
+# Get the full enum map
+event_types:
+  _ref:
+    module: events
+    component: event_types
+
+# Get a single event type's icon
+icon:
+  _ref:
+    module: events
+    component: event_types
+    key: login.icon
+```
+
+## Declaring Plugin Dependencies
+
+Modules declare required plugins with semver version constraints. The build validates these against the app's `plugins` array. Default Lowdefy plugins do not need to be declared — only declare non-default plugins your module requires:
+
+```yaml
+plugins:
+  - name: "@lowdefy/blocks-aggrid"
+    version: "^4"
+```
+
+Use `^major` for major version pinning — the standard convention.
+
+## Declaring Secrets
+
+The `secrets` array is an allowlist. The module can only access secrets it explicitly declares:
+
+```yaml
+secrets:
+  - name: MONGODB
+    description: MongoDB connection URI
+  - name: SENDGRID_API_KEY
+    description: SendGrid API key
+    required: false
+```
+
+## Testing Locally
+
+Create a test app that imports the module via local path:
+
+```yaml
+# test-app/lowdefy.yaml
+lowdefy: LOWDEFY_VERSION
+
+modules:
+  - id: user-admin
+    source: "file:.."
+    vars:
+      roles:
+        _ref: config/test-roles.yaml
+      collection: test_users
+```
+
+Run `lowdefy dev` in the test-app directory. The `file:..` path reads from disk and picks up module changes on rebuild. Include the module multiple times with different vars to test multi-instance behaviour.
+
+## Publishing to GitHub
+
+Publish your module by pushing to a GitHub repository and creating tagged releases:
+
+```bash
+git tag v1.0.0
+git push origin v1.0.0
+```
+
+Consumers reference the tag:
+
+```yaml
+source: "github:my-org/user-admin@v1.0.0"
+```
+
+For monorepos, the path specifies the subdirectory:
+
+```yaml
+source: "github:my-org/modules/user-admin@v1.0.0"
+```
+
+## Versioning Strategy
+
+- **Tags** (e.g., `v1.0.0`) — Recommended for production. Immutable and cacheable.
+- **Branches** (e.g., `main`) — Useful during development. Re-fetched on each build.
+- **Commit SHAs** — Most precise. Immutable.
+
+Follow [semantic versioning](https://semver.org/): increment the major version for breaking changes to the vars interface, minor for new features, patch for fixes.