@slotted/angular 0.0.0-stage → 0.1.0-beta.0

package/docs/scroll-area.json

@@ -0,0 +1,120 @@
+{
+  "family": "scroll-area",
+  "ui": "scroll-area",
+  "binding": "angular",
+  "catalog": {
+    "group": "Layout",
+    "summary": "Scrolling region with styled scrollbars."
+  },
+  "axes": {},
+  "members": {
+    "scrollArea": {
+      "nativeElement": "div",
+      "defaults": {
+        "axis": "block",
+        "scrollbars": "auto",
+        "gutter": "stable",
+        "fade": "both",
+        "overscroll": "contain",
+        "tabbable": true
+      },
+      "capabilities": [
+        "overflow",
+        "appearance",
+        "wiring"
+      ],
+      "states": [
+        "default",
+        "hover",
+        "focus-visible"
+      ],
+      "parts": [
+        "root",
+        "viewport",
+        "content"
+      ]
+    }
+  },
+  "docs": {
+    "accessibility": {
+      "imports": null,
+      "anatomy": [],
+      "api": [],
+      "composition": [],
+      "events": [],
+      "accessibility": []
+    },
+    "anatomy": {
+      "imports": null,
+      "anatomy": [],
+      "api": [],
+      "composition": [],
+      "events": [],
+      "accessibility": []
+    },
+    "api": {
+      "imports": null,
+      "anatomy": [],
+      "api": [],
+      "composition": [],
+      "events": [],
+      "accessibility": []
+    },
+    "composition": {
+      "imports": null,
+      "anatomy": [],
+      "api": [],
+      "composition": [],
+      "events": [],
+      "accessibility": []
+    },
+    "events": {
+      "imports": null,
+      "anatomy": [],
+      "api": [],
+      "composition": [],
+      "events": [],
+      "accessibility": []
+    },
+    "imports": {
+      "imports": null,
+      "anatomy": [],
+      "api": [],
+      "composition": [],
+      "events": [],
+      "accessibility": []
+    },
+    "scenes": {
+      "imports": null,
+      "anatomy": [],
+      "api": [],
+      "composition": [],
+      "events": [],
+      "accessibility": []
+    },
+    "snippets": {
+      "imports": null,
+      "anatomy": [],
+      "api": [],
+      "composition": [],
+      "events": [],
+      "accessibility": []
+    }
+  },
+  "tokens": [
+    "--slotted-border-strong",
+    "--slotted-duration-short",
+    "--slotted-easing-standard",
+    "--slotted-focus-ring-color",
+    "--slotted-focus-ring-offset",
+    "--slotted-focus-ring-width",
+    "--slotted-scroll-area-fade-size",
+    "--slotted-scroll-area-inset",
+    "--slotted-scroll-area-thumb-color",
+    "--slotted-scroll-area-track-color",
+    "--slotted-space-5",
+    "--slotted-space-8",
+    "--slotted-surface-sunken"
+  ],
+  "examples": []
+}

package/docs/scroll-area.md

@@ -0,0 +1,8 @@
+<!-- index: ./index.md -->
+# scroll-area
+
+`data-ui="scroll-area"` · Scrolling region with styled scrollbars.
+
+## Tokens
+
+`--slotted-border-strong`, `--slotted-duration-short`, `--slotted-easing-standard`, `--slotted-focus-ring-color`, `--slotted-focus-ring-offset`, `--slotted-focus-ring-width`, `--slotted-scroll-area-fade-size`, `--slotted-scroll-area-inset`, `--slotted-scroll-area-thumb-color`, `--slotted-scroll-area-track-color`, `--slotted-space-5`, `--slotted-space-8`, `--slotted-surface-sunken`

package/docs/section.json

@@ -0,0 +1,344 @@
+{
+  "family": "section",
+  "ui": "section",
+  "binding": "angular",
+  "catalog": {
+    "group": "Layout",
+    "summary": "Titled block of content within a page."
+  },
+  "axes": {
+    "size": [
+      "sm",
+      "md",
+      "lg"
+    ],
+    "level": [
+      "auto",
+      "1",
+      "2",
+      "3",
+      "4",
+      "5",
+      "6"
+    ],
+    "divider": [
+      false,
+      true
+    ],
+    "ground": [
+      "none",
+      "surface"
+    ],
+    "sticky": [
+      false,
+      true
+    ]
+  },
+  "members": {
+    "section": {
+      "nativeElement": "section",
+      "defaults": {
+        "size": "md",
+        "level": "auto",
+        "divider": false,
+        "ground": "none",
+        "sticky": false
+      },
+      "capabilities": [
+        "size",
+        "appearance",
+        "wiring"
+      ],
+      "states": [
+        "default"
+      ],
+      "parts": [
+        "root",
+        "header",
+        "title",
+        "eyebrow",
+        "heading",
+        "description",
+        "actions",
+        "body"
+      ]
+    }
+  },
+  "docs": {
+    "section": {
+      "imports": {
+        "source": "import { SlSection, SlSectionHeader, SlSectionTitle, SlSectionEyebrow, SlSectionHeading, SlSectionDescription, SlSectionActions, SlSectionBody, provideSectionDefaults } from '@slotted/angular/section';",
+        "selector": "[slSection], [slSectionHeader], [slSectionTitle], [slSectionEyebrow], [slSectionHeading], [slSectionDescription], [slSectionActions], [slSectionBody]",
+        "exportAs": "slSection, slSectionHeading"
+      },
+      "anatomy": [
+        {
+          "part": "root",
+          "element": "the section carrying slSection",
+          "required": true,
+          "purpose": "The unit, carrying data-ui=\"section\", the five inputs, an id a hash link can reach and a scroll margin the height of the page chrome. aria-labelledby its heading once one is rendered, which makes it a region."
+        },
+        {
+          "part": "header",
+          "element": "the element carrying slSectionHeader",
+          "required": false,
+          "purpose": "The row above the body: the title column and the actions. Sticky under the page chrome when sticky is set, painted in the page’s ground so what scrolls under it is covered; its height is measured and added to the sticky top the body publishes, so a table’s column header or a nested section inside stops under it, not under the page."
+        },
+        {
+          "part": "title",
+          "element": "the element carrying slSectionTitle",
+          "required": false,
+          "purpose": "Eyebrow, heading and description, in that order, as one column."
+        },
+        {
+          "part": "eyebrow",
+          "element": "the element carrying slSectionEyebrow",
+          "required": false,
+          "purpose": "A short overline above the heading in small capitals — a count, a category. Structural rather than status: status is a mark beside the heading."
+        },
+        {
+          "part": "heading",
+          "element": "the h1 to h6 carrying slSectionHeading, or any element, which then gets role=\"heading\"",
+          "required": false,
+          "purpose": "The heading. Rendering it is what names the region. A native heading written by the consumer is left alone; a div or a link gets role=\"heading\" and aria-level from the rank the section resolved."
+        },
+        {
+          "part": "description",
+          "element": "the p carrying slSectionDescription",
+          "required": false,
+          "purpose": "A paragraph under the heading, in the muted text, with a measure of seventy characters."
+        },
+        {
+          "part": "actions",
+          "element": "the element carrying slSectionActions",
+          "required": false,
+          "purpose": "The end of the header row: an slButton, an slToolbar, an slLink. It wraps under the title when the width runs out."
+        },
+        {
+          "part": "body",
+          "element": "the element carrying slSectionBody",
+          "required": true,
+          "purpose": "The content, with slHeadingLevel as a host directive, so a section inside it takes the next rank without being told."
+        }
+      ],
+      "api": [
+        {
+          "name": "size",
+          "type": "'sm' | 'md' | 'lg'",
+          "defaultValue": "md",
+          "appliesTo": "slSection, provideSectionDefaults",
+          "description": "The step the heading sits at, on the type scale, independent of its rank"
+        },
+        {
+          "name": "level",
+          "type": "'auto' | '1' | '2' | '3' | '4' | '5' | '6'",
+          "defaultValue": "auto",
+          "appliesTo": "slSection",
+          "description": "The rank of the heading. auto takes the one typography’s outline gives: 2 directly in a page body, one deeper inside another section. A native heading element keeps its own tag; any other element gets aria-level from this"
+        },
+        {
+          "name": "divider",
+          "type": "boolean",
+          "defaultValue": "false",
+          "appliesTo": "slSection, provideSectionDefaults",
+          "description": "A rule under the header, for a page where space alone does not separate"
+        },
+        {
+          "name": "ground",
+          "type": "'none' | 'surface'",
+          "defaultValue": "none",
+          "appliesTo": "slSection, provideSectionDefaults",
+          "description": "none is transparent; surface paints the raised surface with a subtle edge and the large radius — no shadow, no hover, no action, because a section is not a card"
+        },
+        {
+          "name": "sticky",
+          "type": "boolean",
+          "defaultValue": "false",
+          "appliesTo": "slSection, provideSectionDefaults",
+          "description": "The header stays under the page chrome while the body scrolls, painted in the page’s ground. Without a page it sticks to the top of whatever scrolls"
+        },
+        {
+          "name": "id",
+          "type": "attribute",
+          "defaultValue": "generated",
+          "appliesTo": "slSection",
+          "description": "The identifier a hash link reaches, read with HostAttributeToken. The heading’s own id is derived from it"
+        }
+      ],
+      "composition": [
+        {
+          "name": "slSectionHeading on any element",
+          "type": "directive",
+          "defaultValue": "—",
+          "appliesTo": "the consumer’s own element",
+          "description": "A native heading gets nothing added; a div or a link gets role=\"heading\" and aria-level, so a linked or editable title keeps its rank"
+        },
+        {
+          "name": "exportAs slSection",
+          "type": "SlSection",
+          "defaultValue": "—",
+          "appliesTo": "a template reference",
+          "description": "The resolved rank, size, ground and the identifiers, as signals"
+        },
+        {
+          "name": "provideSectionDefaults()",
+          "type": "{ size, divider, ground, sticky }",
+          "defaultValue": "—",
+          "appliesTo": "an injector",
+          "description": "The four decisions an application takes once. A section that states any of them itself still wins"
+        },
+        {
+          "name": "slHeadingLevel",
+          "type": "from @slotted/angular/typography",
+          "defaultValue": "—",
+          "appliesTo": "around a subtree",
+          "description": "The outline context the section reads. The body already carries it as a host directive; put it on an element yourself to step the outline elsewhere"
+        },
+        {
+          "name": "native attributes",
+          "type": "on every part",
+          "defaultValue": "—",
+          "appliesTo": "every part",
+          "description": "Every directive sits on the consumer’s own element, so id, class, routerLink and every listener stay where they were written"
+        }
+      ],
+      "events": [],
+      "accessibility": [
+        "The practice is the WAI-ARIA APG’s Landmark Regions (w3.org/WAI/ARIA/apg/practices/landmark-regions/): a section element with an accessible name is a region landmark. The root is aria-labelledby its heading once one is rendered, so a section with a heading appears in the landmark list under the heading’s words, and one without a heading is a plain section that clutters nothing.",
+        "The rank is real and the element is the consumer’s. Write h2 and the directive adds nothing; write a div or a link and it gets role=\"heading\" and aria-level from the outline typography keeps — 2 directly in a page body, one deeper inside another section’s body — or from level.",
+        "The body carries slHeadingLevel as a host directive, which is what keeps a nested section, a collapsible or a table caption at the right rank without either family reading the other. The HTML Standard requires each heading to be at most one deeper than the one before, and stepping by exactly one is the only way to hold that in a tree assembled from components.",
+        "The root carries a scroll margin the height of the page chrome, so a hash link to the section lands under the header rather than behind it. The id is the consumer’s or a generated one, and the heading’s id is derived from it, so an anchor-nav family later has both to reach.",
+        "Nothing here is interactive. The actions slot holds the consumer’s own controls, in the page tab sequence like any other; the sticky header is CSS and takes no focus."
+      ]
+    }
+  },
+  "tokens": [
+    "--slotted-border-subtle",
+    "--slotted-border-width-thin",
+    "--slotted-control-gap-md",
+    "--slotted-font-family-heading",
+    "--slotted-font-family-sans",
+    "--slotted-font-size-lg",
+    "--slotted-font-size-md",
+    "--slotted-font-size-sm",
+    "--slotted-font-size-xl",
+    "--slotted-font-size-xs",
+    "--slotted-font-weight-semibold",
+    "--slotted-line-height-lg",
+    "--slotted-line-height-md",
+    "--slotted-line-height-sm",
+    "--slotted-line-height-xl",
+    "--slotted-line-height-xs",
+    "--slotted-page-ground",
+    "--slotted-radius-lg",
+    "--slotted-section-border",
+    "--slotted-section-description-measure",
+    "--slotted-section-gap",
+    "--slotted-section-heading-size-lg",
+    "--slotted-section-heading-size-md",
+    "--slotted-section-heading-size-sm",
+    "--slotted-section-inset",
+    "--slotted-section-radius",
+    "--slotted-section-surface",
+    "--slotted-space-1",
+    "--slotted-space-3",
+    "--slotted-space-4",
+    "--slotted-space-5",
+    "--slotted-space-6",
+    "--slotted-surface",
+    "--slotted-surface-raised",
+    "--slotted-text",
+    "--slotted-text-muted",
+    "--slotted-z-index-sticky"
+  ],
+  "examples": [
+    {
+      "id": "playground",
+      "title": "Playground",
+      "note": "One section of a purchase order with every input on it, driven by the controls below the canvas. It sits inside a page, so its rank is h2 and its sticky header stops under the page chrome.",
+      "language": "html",
+      "source": "<section slSection>\n  <div slSectionHeader>\n    <div slSectionTitle><h2 slSectionHeading>Itens do pedido</h2></div>\n  </div>\n  <div slSectionBody>…</div>\n</section>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "anatomy",
+      "title": "Every part, written out",
+      "note": "The eyebrow with the count, the heading, the description under it, two actions at the end of the row, and the body with the table. The section is a region named by its heading.",
+      "language": "html",
+      "source": "<section slSection divider id=\"itens\">\n  <div slSectionHeader>\n    <div slSectionTitle>\n      <span slSectionEyebrow>36 itens</span>\n      <h2 slSectionHeading>Itens do pedido</h2>\n      <p slSectionDescription>Quantidades conforme a cotação aceite.</p>\n    </div>\n    <div slSectionActions><button slButton size=\"sm\" variant=\"outline\">Exportar</button></div>\n  </div>\n  <div slSectionBody><div slTable>…</div></div>\n</section>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "level",
+      "title": "The rank is the outline’s",
+      "note": "Three sections nested with div headings: role=\"heading\" at level 2 directly in the page, 3 inside it, 4 inside that — none of them told. level=\"5\" on the last one overrides the outline.",
+      "language": "html",
+      "source": "<section slSection>\n  <div slSectionHeading>Frota</div>\n  <div slSectionBody>\n    <section slSection><div slSectionHeading>Veículos pesados</div></section>\n  </div>\n</section>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "size",
+      "title": "The step the heading sits at",
+      "note": "sm for a group inside a form, md for a section of a page, lg for the one section a screen is about. The step is a size on the type scale and says nothing about the rank.",
+      "language": "html",
+      "source": "<section slSection level=\"3\" size=\"lg\">…</section>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "separation",
+      "title": "Space, a rule, or a surface",
+      "note": "Three sections on the page’s sunken canvas: separated by the stack’s gap alone, by a divider under the header, and by a surface with an edge and a radius — no shadow, no hover, because a section is not a card.",
+      "language": "html",
+      "source": "<section slSection ground=\"surface\">…</section>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "sticky",
+      "title": "A header that stays",
+      "note": "Scroll the screen: each section’s header stops under the page chrome and the next one pushes it away. Pin the page header and they all stop lower, because the page publishes where its chrome ends. A sticky section republishes it for its body as page plus header, so layers add up: a section in a section, a table in that.",
+      "language": "html",
+      "source": "<section slSection sticky>…</section>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "nested",
+      "title": "A section inside a section",
+      "note": "The fleet, its heavy vehicles, the tractors: three depths, three ranks, and every rule the family owns reaches its parts with a child combinator, so the outer header styles nothing of the inner one.",
+      "language": "html",
+      "source": "<section slSection size=\"lg\">\n  <div slSectionHeading>Frota</div>\n  <div slSectionBody>\n    <section slSection>\n      <div slSectionHeading>Veículos pesados</div>\n      <div slSectionBody>\n        <section slSection size=\"sm\"><div slSectionHeading>Cavalos mecânicos</div></section>\n      </div>\n    </section>\n  </div>\n</section>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "content",
+      "title": "Content the family did not choose",
+      "note": "A nine-word heading wraps, a long eyebrow wraps in small capitals, a translated description keeps its measure, and a header with no actions leaves no vacancy at the end of the row.",
+      "language": "html",
+      "source": "<h2 slSectionHeading>\n  Requisitos de homologação, garantia, recapagem e descarte ambientalmente adequado dos pneus\n  fornecidos\n</h2>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "composition",
+      "title": "A section with a table, a collapsible and a description list in it",
+      "note": "The body holds other families and steps the outline for them: the collapsible’s header sits one rank under the section. Scroll and the sticky header stays over all of it.",
+      "language": "html",
+      "source": "<div slSectionBody><div slTable stickyHeader stickyTo=\"page\">…</div></div>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "defaults",
+      "title": "Setting it once, and reaching past it",
+      "note": "provideSectionDefaults carries size, divider, ground and sticky for every section under it; the heading directive sits on the consumer’s own link while the family keeps the rank; a hash link reaches the root by its id.",
+      "language": "ts",
+      "source": "bootstrapApplication(App, {\n  providers: [provideSectionDefaults({ divider: true, size: 'sm' })],\n});\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "accessibility",
+      "title": "What a reader hears",
+      "note": "A section with a heading is a region in the landmark list, named by the heading; one without a heading is a plain section, absent from it. Jump to a section by hash and it lands under the page chrome, not behind it.",
+      "language": "html",
+      "source": "<a slLink href=\"#historico\">Ir ao histórico</a>\n",
+      "verdict": "excerpt"
+    }
+  ]
+}