@almadar/std 16.239.0 → 16.242.0

package/behaviors/registry/ui/core/atoms/std-doc-page.orb

@@ -0,0 +1,594 @@
+{
+  "description": "std-doc-page — one page of a documentation site: a section sidebar with the current page marked, a breadcrumb, the page title and lede, an \"on this page\" contents list, the page's own content (a render slot the call site fills, live behaviors included) and previous/next links. Supports right-to-left pages. Pick for docs sites, handbooks, reference manuals and knowledge bases.",
+  "ledger": {
+    "entries": {
+      "ent_01M43K1FHRYTT5PNFT582WQXZW": {
+        "bakedName": "DocPageView",
+        "curName": "DocPageView",
+        "id": "ent_01M43K1FHRYTT5PNFT582WQXZW",
+        "kind": "entity",
+        "owner": "workspace",
+        "renames": []
+      },
+      "evt_01M43K1FHR92JR8S2DM4A21077": {
+        "bakedName": "INIT",
+        "curName": "INIT",
+        "id": "evt_01M43K1FHR92JR8S2DM4A21077",
+        "kind": "event",
+        "owner": "workspace",
+        "parent": "trt_01M43K1FHRYW1PQFJW58SCAR5G",
+        "renames": []
+      },
+      "orb_01M43K1FHR4DQC862G3EGD338S": {
+        "bakedName": "DocPageOrbital",
+        "curName": "DocPageOrbital",
+        "id": "orb_01M43K1FHR4DQC862G3EGD338S",
+        "kind": "orbital",
+        "owner": "workspace",
+        "renames": []
+      },
+      "pag_01M43K1FHRMA9XWQM1RNX61RP3": {
+        "bakedName": "DocPage",
+        "curName": "DocPage",
+        "id": "pag_01M43K1FHRMA9XWQM1RNX61RP3",
+        "kind": "page",
+        "owner": "workspace",
+        "renames": []
+      },
+      "trt_01M43K1FHRYW1PQFJW58SCAR5G": {
+        "bakedName": "DocPageRender",
+        "curName": "DocPageRender",
+        "id": "trt_01M43K1FHRYW1PQFJW58SCAR5G",
+        "kind": "trait",
+        "owner": "workspace",
+        "renames": []
+      }
+    },
+    "schemaVersion": 1
+  },
+  "name": "std-doc-page",
+  "orbitals": [
+    {
+      "entity": {
+        "fields": [
+          {
+            "name": "id",
+            "required": true,
+            "type": "string"
+          }
+        ],
+        "id": "ent_01M43K1FHRYTT5PNFT582WQXZW",
+        "name": "DocPageView",
+        "persistence": "runtime"
+      },
+      "id": "orb_01M43K1FHR4DQC862G3EGD338S",
+      "name": "DocPageOrbital",
+      "pages": [
+        {
+          "id": "pag_01M43K1FHRMA9XWQM1RNX61RP3",
+          "name": "DocPage",
+          "path": "/doc",
+          "traits": [
+            {
+              "ref": "DocPageRender",
+              "refId": "trt_01M43K1FHRYW1PQFJW58SCAR5G"
+            }
+          ]
+        }
+      ],
+      "traits": [
+        {
+          "category": "interaction",
+          "config": {
+            "content": {
+              "default": {
+                "children": [],
+                "direction": "vertical",
+                "gap": "lg",
+                "type": "stack"
+              },
+              "description": "The page body: markdown, code and live behaviors (trait references) in reading order",
+              "label": "Content",
+              "tier": "presentation",
+              "type": "render-ui"
+            },
+            "crumbs": {
+              "default": [],
+              "description": "Ancestors first, the current page last without a link; empty hides it",
+              "items": {
+                "properties": {
+                  "href": {
+                    "name": "href",
+                    "required": false,
+                    "type": "string"
+                  },
+                  "label": {
+                    "name": "label",
+                    "required": true,
+                    "type": "string"
+                  }
+                },
+                "type": "object"
+              },
+              "label": "Breadcrumb",
+              "tier": "presentation",
+              "type": "[DocCrumb]"
+            },
+            "direction": {
+              "default": "ltr",
+              "label": "Direction",
+              "tier": "presentation",
+              "type": "string",
+              "values": [
+                "ltr",
+                "rtl"
+              ]
+            },
+            "lede": {
+              "default": "",
+              "description": "One or two sentences under the title; empty hides it",
+              "label": "Lede",
+              "tier": "presentation",
+              "type": "string"
+            },
+            "navItems": {
+              "default": [],
+              "description": "The documentation tree; mark the current page active",
+              "items": {
+                "properties": {
+                  "active": {
+                    "name": "active",
+                    "required": false,
+                    "type": "boolean"
+                  },
+                  "href": {
+                    "name": "href",
+                    "required": false,
+                    "type": "string"
+                  },
+                  "items": {
+                    "items": {
+                      "type": "union",
+                      "values": [
+                        "DocNavItem"
+                      ]
+                    },
+                    "name": "items",
+                    "required": false,
+                    "type": "array"
+                  },
+                  "label": {
+                    "name": "label",
+                    "required": true,
+                    "type": "string"
+                  }
+                },
+                "type": "object"
+              },
+              "label": "Sidebar",
+              "tier": "presentation",
+              "type": "[DocNavItem]"
+            },
+            "next": {
+              "default": {
+                "href": "",
+                "label": ""
+              },
+              "description": "Empty href hides it",
+              "label": "Next page",
+              "properties": {
+                "category": {
+                  "name": "category",
+                  "required": false,
+                  "type": "string"
+                },
+                "href": {
+                  "name": "href",
+                  "required": true,
+                  "type": "string"
+                },
+                "label": {
+                  "name": "label",
+                  "required": true,
+                  "type": "string"
+                }
+              },
+              "tier": "presentation",
+              "type": "DocLink"
+            },
+            "prev": {
+              "default": {
+                "href": "",
+                "label": ""
+              },
+              "description": "Empty href hides it",
+              "label": "Previous page",
+              "properties": {
+                "category": {
+                  "name": "category",
+                  "required": false,
+                  "type": "string"
+                },
+                "href": {
+                  "name": "href",
+                  "required": true,
+                  "type": "string"
+                },
+                "label": {
+                  "name": "label",
+                  "required": true,
+                  "type": "string"
+                }
+              },
+              "tier": "presentation",
+              "type": "DocLink"
+            },
+            "sidebarLabel": {
+              "default": "Documentation",
+              "label": "Sidebar label",
+              "tier": "presentation",
+              "type": "string"
+            },
+            "title": {
+              "default": "Untitled page",
+              "label": "Title",
+              "tier": "presentation",
+              "type": "string"
+            },
+            "toc": {
+              "default": [],
+              "description": "Anchors of the page's sections (each section declares the same id); empty hides it",
+              "items": {
+                "properties": {
+                  "id": {
+                    "name": "id",
+                    "required": true,
+                    "type": "string"
+                  },
+                  "label": {
+                    "name": "label",
+                    "required": true,
+                    "type": "string"
+                  },
+                  "level": {
+                    "name": "level",
+                    "required": true,
+                    "type": "number"
+                  }
+                },
+                "type": "object"
+              },
+              "label": "On this page",
+              "tier": "presentation",
+              "type": "[DocTocEntry]"
+            },
+            "tocLabel": {
+              "default": "On this page",
+              "label": "Contents label",
+              "tier": "presentation",
+              "type": "string"
+            }
+          },
+          "effectRow": [
+            {
+              "kind": "render-ui",
+              "resource": "main"
+            }
+          ],
+          "entityContract": {
+            "provides": [],
+            "requires": []
+          },
+          "entityRebindable": true,
+          "entityRefIds": {
+            "DocPageView": "ent_01M43K1FHRYTT5PNFT582WQXZW"
+          },
+          "id": "trt_01M43K1FHRYW1PQFJW58SCAR5G",
+          "linkedEntity": "DocPageView",
+          "linkedEntityId": "ent_01M43K1FHRYTT5PNFT582WQXZW",
+          "name": "DocPageRender",
+          "scope": "instance",
+          "stateMachine": {
+            "events": [
+              {
+                "id": "evt_01M43K1FHR92JR8S2DM4A21077",
+                "key": "INIT",
+                "name": "Initialize"
+              }
+            ],
+            "states": [
+              {
+                "isInitial": true,
+                "name": "idle"
+              }
+            ],
+            "transitions": [
+              {
+                "effects": [
+                  [
+                    "render-ui",
+                    "main",
+                    {
+                      "children": [
+                        {
+                          "children": [
+                            {
+                              "children": [
+                                {
+                                  "children": [
+                                    {
+                                      "className": [
+                                        "if",
+                                        [
+                                          "==",
+                                          "@config.sidebarLabel",
+                                          ""
+                                        ],
+                                        "hidden",
+                                        "px-3"
+                                      ],
+                                      "content": "@config.sidebarLabel",
+                                      "type": "typography",
+                                      "variant": "label",
+                                      "weight": "semibold"
+                                    },
+                                    {
+                                      "aria-label": "@config.sidebarLabel",
+                                      "items": "@config.navItems",
+                                      "type": "doc-sidebar"
+                                    }
+                                  ],
+                                  "className": "lg:sticky lg:top-6 self-start",
+                                  "direction": "vertical",
+                                  "gap": "sm",
+                                  "type": "stack"
+                                },
+                                {
+                                  "children": [
+                                    {
+                                      "className": [
+                                        "if",
+                                        [
+                                          "==",
+                                          [
+                                            "array/len",
+                                            "@config.crumbs"
+                                          ],
+                                          0.0
+                                        ],
+                                        "hidden",
+                                        ""
+                                      ],
+                                      "items": "@config.crumbs",
+                                      "type": "doc-breadcrumb"
+                                    },
+                                    {
+                                      "children": [
+                                        {
+                                          "className": "tracking-tight text-balance",
+                                          "content": "@config.title",
+                                          "type": "typography",
+                                          "variant": "h1",
+                                          "weight": "bold"
+                                        },
+                                        {
+                                          "className": [
+                                            "if",
+                                            [
+                                              "==",
+                                              "@config.lede",
+                                              ""
+                                            ],
+                                            "hidden",
+                                            "max-w-3xl text-pretty"
+                                          ],
+                                          "color": "muted",
+                                          "content": "@config.lede",
+                                          "type": "typography",
+                                          "variant": "large"
+                                        }
+                                      ],
+                                      "direction": "vertical",
+                                      "gap": "sm",
+                                      "type": "stack"
+                                    },
+                                    {
+                                      "bg": "muted",
+                                      "children": [
+                                        {
+                                          "children": [
+                                            {
+                                              "content": "@config.tocLabel",
+                                              "type": "typography",
+                                              "variant": "label",
+                                              "weight": "semibold"
+                                            },
+                                            {
+                                              "aria-label": "@config.tocLabel",
+                                              "items": "@config.toc",
+                                              "type": "doc-toc"
+                                            }
+                                          ],
+                                          "direction": "vertical",
+                                          "gap": "xs",
+                                          "type": "stack"
+                                        }
+                                      ],
+                                      "className": [
+                                        "if",
+                                        [
+                                          "==",
+                                          [
+                                            "array/len",
+                                            "@config.toc"
+                                          ],
+                                          0.0
+                                        ],
+                                        "hidden",
+                                        ""
+                                      ],
+                                      "padding": "md",
+                                      "rounded": "lg",
+                                      "type": "box"
+                                    },
+                                    "@config.content",
+                                    {
+                                      "type": "divider"
+                                    },
+                                    {
+                                      "next": [
+                                        "if",
+                                        [
+                                          "==",
+                                          [
+                                            "object/get",
+                                            "@config.next",
+                                            "href",
+                                            ""
+                                          ],
+                                          ""
+                                        ],
+                                        null,
+                                        "@config.next"
+                                      ],
+                                      "prev": [
+                                        "if",
+                                        [
+                                          "==",
+                                          [
+                                            "object/get",
+                                            "@config.prev",
+                                            "href",
+                                            ""
+                                          ],
+                                          ""
+                                        ],
+                                        null,
+                                        "@config.prev"
+                                      ],
+                                      "type": "doc-pagination"
+                                    }
+                                  ],
+                                  "className": "min-w-0",
+                                  "direction": "vertical",
+                                  "gap": "lg",
+                                  "type": "stack"
+                                }
+                              ],
+                              "gap": "xl",
+                              "ratio": "1:4",
+                              "type": "split"
+                            }
+                          ],
+                          "maxWidth": "xl",
+                          "padding": "lg",
+                          "size": "xl",
+                          "type": "container"
+                        }
+                      ],
+                      "dir": "@config.direction",
+                      "fullWidth": true,
+                      "paddingY": "lg",
+                      "type": "box"
+                    }
+                  ]
+                ],
+                "event": "INIT",
+                "eventId": "evt_01M43K1FHR92JR8S2DM4A21077",
+                "from": "idle",
+                "to": "idle"
+              }
+            ]
+          }
+        }
+      ],
+      "types": {
+        "DocCrumb": [
+          {
+            "name": "label",
+            "required": true,
+            "type": "string"
+          },
+          {
+            "name": "href",
+            "type": "string"
+          }
+        ],
+        "DocLink": [
+          {
+            "name": "label",
+            "required": true,
+            "type": "string"
+          },
+          {
+            "name": "href",
+            "required": true,
+            "type": "string"
+          },
+          {
+            "name": "category",
+            "type": "string"
+          }
+        ],
+        "DocNavItem": [
+          {
+            "name": "label",
+            "required": true,
+            "type": "string"
+          },
+          {
+            "name": "href",
+            "type": "string"
+          },
+          {
+            "name": "items",
+            "properties": [
+              {
+                "name": "label",
+                "required": true,
+                "type": "string"
+              },
+              {
+                "name": "href",
+                "type": "string"
+              },
+              {
+                "name": "items",
+                "properties": [],
+                "type": "[DocNavItem]"
+              },
+              {
+                "name": "active",
+                "type": "boolean"
+              }
+            ],
+            "type": "[object]"
+          },
+          {
+            "name": "active",
+            "type": "boolean"
+          }
+        ],
+        "DocTocEntry": [
+          {
+            "name": "id",
+            "required": true,
+            "type": "string"
+          },
+          {
+            "name": "label",
+            "required": true,
+            "type": "string"
+          },
+          {
+            "name": "level",
+            "required": true,
+            "type": "number"
+          }
+        ]
+      }
+    }
+  ],
+  "schemaVersion": 1,
+  "version": "1.0.0"
+}

package/behaviors/registry/ui/core/atoms/std-site-header.orb

@@ -1,5 +1,5 @@
 {
-  "description": "std-site-header — the sticky top bar of a public website: brand (logo + name), navigation links with the current page marked (a link with children opens a dropdown), an optional language picker (std-language-picker: the same page in each language, default language at the root and the others under /<code>/), and an optional call-to-action button. On small screens the links fold into a menu opened by a toggle, with child links indented under their parent and the call-to-action button at the bottom. Links follow `href` (in-app path, #anchor, or absolute URL); the header action and the small-screen menu links also emit NAV_CLICKED { href, label }. Pick for marketing sites, docs portals and product websites; for signed-in app chrome use std-app-layout.",
+  "description": "std-site-header — the sticky top bar of a public website: brand (logo + name, linking home when `homeHref` is set), navigation links with the current page marked (a link with children opens a dropdown), an optional light/dark toggle, an optional language picker (std-language-picker: the same page in each language, default language at the root and the others under /<code>/), and an optional call-to-action button. On small screens the links fold into a menu opened by a toggle, with child links indented under their parent and the call-to-action button at the bottom. Links follow `href` (in-app path, #anchor, or absolute URL); the header action and the small-screen menu links also emit NAV_CLICKED { href, label }. Pick for marketing sites, docs portals and product websites; for signed-in app chrome use std-app-layout.",
   "ledger": {
     "entries": {
       "ent_01M3B9EHRNR3JQPJSD36PH5QV8": {
@@ -166,6 +166,16 @@
                   {
                     "actions": [
                       "@trait.SiteHeaderLanguages",
+                      {
+                        "className": [
+                          "if",
+                          "@config.showThemeToggle",
+                          "",
+                          "hidden"
+                        ],
+                        "size": "sm",
+                        "type": "theme-toggle"
+                      },
                       {
                         "action": "NAV_LINK",
                         "actionPayload": {
@@ -189,6 +199,7 @@
                         "variant": "primary"
                       }
                     ],
+                    "brandHref": "@config.homeHref",
                     "brandName": "@config.brandName",
                     "className": "hidden lg:flex",
                     "logoSrc": "@config.logoSrc",
@@ -268,8 +279,19 @@
                   },
                   {
                     "actions": [
-                      "@trait.SiteHeaderLanguages"
+                      "@trait.SiteHeaderLanguages",
+                      {
+                        "className": [
+                          "if",
+                          "@config.showThemeToggle",
+                          "",
+                          "hidden"
+                        ],
+                        "size": "sm",
+                        "type": "theme-toggle"
+                      }
                     ],
+                    "brandHref": "@config.homeHref",
                     "brandName": "@config.brandName",
                     "className": "lg:hidden",
                     "isMenuOpen": "@entity.menuOpen",
@@ -464,6 +486,14 @@
               "tier": "internal",
               "type": "render-ui"
             },
+            "homeHref": {
+              "default": "",
+              "description": "Where the brand (logo + name) links to, usually the site's home page; empty leaves the brand unlinked",
+              "label": "Home link",
+              "synonyms": "logo link, home page, brand link",
+              "tier": "presentation",
+              "type": "string"
+            },
             "languages": {
               "default": [],
               "description": "Every language this page exists in, each named in its own language, with the href of THIS page in that language (default language at the root, others under /<code>/). Empty hides the language picker.",
@@ -544,6 +574,14 @@
               "label": "Logo image",
               "tier": "presentation",
               "type": "string"
+            },
+            "showThemeToggle": {
+              "default": false,
+              "description": "Show a button that switches the site between its light and dark mode",
+              "label": "Light/dark toggle",
+              "synonyms": "dark mode, theme switch, color mode",
+              "tier": "presentation",
+              "type": "boolean"
             }
           },
           "effectRow": [