npm - @schalkneethling/toolkit - Versions diffs - 0.1.0 - Mend

@schalkneethling/toolkit 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (11) hide show

package/LICENSE +21 -0
package/README.md +103 -0
package/dist/index.d.mts +1 -0
package/dist/index.mjs +292 -0
package/dist/index.mjs.map +1 -0
package/hooks/block-dangerous-commands/hook.js +120 -0
package/hooks/block-dangerous-commands/settings-fragment.json +15 -0
package/package.json +35 -0
package/skills/semantic-html/SKILL.md +603 -0
package/skills/semantic-html/references/element-decision-trees.md +111 -0
package/skills/semantic-html/references/heading-patterns.md +275 -0

package/skills/semantic-html/references/element-decision-trees.md ADDED Viewed

@@ -0,0 +1,111 @@
+# Element Decision Trees
+Quick decision frameworks for selecting the right HTML element.
+## Is It a List?
+```
+Does knowing the count help the user?
+├─ Yes → Are items sequential/ranked?
+│        ├─ Yes → <ol>
+│        └─ No → <ul>
+├─ No → Are these term-description pairs?
+│       ├─ Yes → <dl>
+│       └─ No → Consider plain elements with appropriate structure
+└─ Is it a toolbar of commands?
+   └─ Yes → <menu>
+```
+## Is It a Table?
+```
+Does data have meaningful rows AND columns?
+├─ No → Not a table
+│       ├─ One dimension only → List or plain elements
+│       ├─ Key-value pairs → <dl>
+│       └─ Hierarchical → Nested lists or other structure
+└─ Yes → Does each row have the same columns?
+         ├─ No → Reconsider data structure
+         └─ Yes → Use <table> with full semantics
+```
+## Button or Link?
+```
+Does this navigate to a new URL?
+├─ Yes → <a href="...">
+└─ No → Does an action occur?
+        ├─ Yes → Would a URL provide useful fallback if JS fails?
+        │        ├─ Yes → <a href="..."> with JS enhancement
+        │        └─ No → <button>
+        └─ No → Reconsider if interaction is needed
+```
+## Section or Div?
+```
+Does this content form a thematic grouping?
+├─ No → <div>
+└─ Yes → Can you provide a meaningful accessible name?
+         ├─ Yes → <section aria-labelledby="...">
+         └─ No → <div> (section without label ≈ div semantically)
+```
+## Article Candidate?
+```
+Would this content make sense standalone?
+├─ Yes → Could it be syndicated or extracted?
+│        ├─ Yes → <article>
+│        └─ No → Use appropriate container (section, div, etc.)
+└─ No → Use appropriate container (section, div, etc.)
+```
+## Which Landmark?
+```
+What is this section's purpose?
+├─ Site/section header → <header>
+├─ Site/section footer → <footer>
+├─ Navigation → <nav> (must be labelled)
+├─ Primary page content → <main>
+├─ Search/filter functionality → <search> (wrap ALL related controls, not just the text input)
+├─ User input → <form> (must be labelled to be a landmark)
+├─ Tangentially related → <aside>
+├─ Self-contained content → <article>
+└─ Thematic grouping with label → <section aria-labelledby="...">
+```
+## Form Field Grouping
+```
+Do these fields form a logical/thematic group?
+├─ Yes → Are they form controls (inputs, selects, checkboxes)?
+│        ├─ Yes → <fieldset> with <legend>
+│        └─ No → <section aria-labelledby="...">
+└─ No → Is visual grouping needed?
+        ├─ Yes → <div> with appropriate styling
+        └─ No → Fields can exist without wrapper
+```
+## Interactive Disclosure
+```
+Should content be expandable/collapsible?
+├─ Yes → Does the disclosed content need ARIA roles (menu, dialog, etc.)?
+│        ├─ Yes → <button> controlling visibility + appropriate ARIA
+│        └─ No → Is it a single content section?
+│                ├─ Yes → <details>/<summary>
+│                └─ No → Consider tab pattern or custom disclosure
+└─ No → Is it a list of definitions?
+        └─ Yes → <dl> (not details/summary)
+```
+## Skip Navigation
+```
+Does the page have a <nav> or repeated content before <main>?
+└─ Yes → Add <a href="#main-content"> as the first element in <body>
+         Does the page have a prominent search bar or long sidebar?
+         └─ Yes → Add additional skip links to those targets
+```

package/skills/semantic-html/references/heading-patterns.md ADDED Viewed

@@ -0,0 +1,275 @@
+# Heading Patterns in Component Systems
+Strategies for maintaining proper heading hierarchy in component-based architectures.
+## The Challenge
+Component-based development creates a tension:
+- Components should be reusable across contexts
+- Heading levels depend on surrounding document structure
+- Content authors may not understand heading hierarchy
+- Hardcoded levels break in different contexts
+## Pattern 1: Configurable Heading Level
+Make heading level a prop/parameter with a sensible default.
+```jsx
+// React example
+function Card({ title, headingLevel = 3, children }) {
+  const Heading = `h${headingLevel}`;
+  return (
+    <article className="card">
+      <Heading>{title}</Heading>
+      {children}
+    </article>
+  );
+}
+```
+```twig
+{# Twig example #}
+{% set heading_tag = heading_level|default(3) %}
+<article class="card">
+  <h{{ heading_tag }}>{{ title }}</h{{ heading_tag }}>
+  {{ content }}
+</article>
+```
+### When to Use
+- Generic components used in multiple contexts
+- Components where nesting depth varies
+- CMS-driven content where authors control usage
+### Trade-offs
+- Moves responsibility to component consumer
+- Authors may not choose correctly
+- Sensible default reduces but doesn't eliminate risk
+## Pattern 2: Context-Aware Defaults
+Set defaults based on known component relationships.
+```jsx
+// Section always starts a new heading context
+function Section({ title, children }) {
+  return (
+    <section aria-labelledby="section-title">
+      <h2 id="section-title">{title}</h2>
+      {children}
+    </section>
+  );
+}
+// Cards within sections default to h3
+function CardList({ cards }) {
+  return (
+    <ul className="card-list">
+      {cards.map((card) => (
+        <li key={card.id}>
+          <Card title={card.title} headingLevel={3} />
+        </li>
+      ))}
+    </ul>
+  );
+}
+```
+### When to Use
+- Known parent-child component relationships
+- Design systems with predictable nesting patterns
+- When you control both container and child components
+### Trade-offs
+- Less flexible
+- Breaks if components are used outside expected context
+- Requires documentation of expected usage
+## Pattern 3: Heading Component Abstraction
+Create a heading component that handles both semantic and visual concerns.
+```jsx
+function Heading({ level, visualLevel = level, children, className = "" }) {
+  const Tag = `h${level}`;
+  const visualClass = `u-heading-${visualLevel}`;
+  return <Tag className={`${visualClass} ${className}`}>{children}</Tag>;
+}
+// Usage: semantic h3, visual appearance of h2
+<Heading level={3} visualLevel={2}>
+  Section Title
+</Heading>;
+```
+### When to Use
+- Design requires visual hierarchy different from semantic
+- Large headings needed at deep nesting levels
+- Consistent visual treatment across varying semantic levels
+### Benefits
+- Separates concerns clearly
+- Documents the distinction explicitly
+- Enables correct semantics without design compromise
+## Pattern 4: Inherited Configuration
+Generic components inherit heading config when specialised.
+```jsx
+// Generic card
+function Card({ title, headingLevel = 3, headingClass, children }) {
+  const Heading = `h${headingLevel}`;
+  return (
+    <article className="card">
+      <Heading className={headingClass}>{title}</Heading>
+      {children}
+    </article>
+  );
+}
+// Specialised product card - knows its context
+function ProductCard({ product, headingLevel = 3 }) {
+  return (
+    <Card
+      title={product.name}
+      headingLevel={headingLevel}
+      headingClass="product-card__title"
+    >
+      <p className="product-card__price">{product.price}</p>
+      <p className="product-card__description">{product.description}</p>
+    </Card>
+  );
+}
+// Page section - sets context for children
+function FeaturedProducts({ products }) {
+  return (
+    <section aria-labelledby="featured-heading">
+      <h2 id="featured-heading">Featured Products</h2>
+      <ul className="product-grid">
+        {products.map((product) => (
+          <li key={product.id}>
+            <ProductCard product={product} headingLevel={3} />
+          </li>
+        ))}
+      </ul>
+    </section>
+  );
+}
+```
+### When to Use
+- Design systems with component inheritance
+- When generic components are always wrapped by specific ones
+- Clear ownership of heading level decision
+## Visual-Only Headings
+When text should look like a heading but not affect document outline:
+```html
+<!-- Looks like a heading, but isn't one semantically -->
+<p class="u-heading-xl">Sale ends tomorrow!</p>
+<!-- Compare to actual heading -->
+<h2 class="u-heading-xl">Product Categories</h2>
+```
+### When to Use
+- Promotional text that looks prominent but isn't structural
+- Decorative typography
+- Labels that don't introduce content sections
+### CSS Utility Classes
+```css
+/* Size-based utilities separate from semantic level */
+.u-heading-xs {
+  font-size: var(--font-size-xs);
+}
+.u-heading-s {
+  font-size: var(--font-size-s);
+}
+.u-heading-m {
+  font-size: var(--font-size-m);
+}
+.u-heading-l {
+  font-size: var(--font-size-l);
+}
+.u-heading-xl {
+  font-size: var(--font-size-xl);
+}
+/* All share heading-like properties */
+.u-heading-xs,
+.u-heading-s,
+.u-heading-m,
+.u-heading-l,
+.u-heading-xl {
+  font-weight: var(--font-weight-bold);
+  line-height: var(--line-height-tight);
+}
+```
+## Checklist for Component Headings
+When building a component with a heading:
+- [ ] Is the heading level configurable?
+- [ ] Is there a sensible default?
+- [ ] Is the default documented?
+- [ ] Can visual appearance be controlled independently?
+- [ ] Does the component work at all reasonable heading levels?
+- [ ] Is the expected context documented?
+## Common Mistakes
+### Hardcoded Levels
+```jsx
+// Fragile: breaks when used outside expected context
+function Card({ title }) {
+  return (
+    <article>
+      <h3>{title}</h3> {/* What if this is used at h2 level? */}
+    </article>
+  );
+}
+```
+### Level Chosen for Appearance
+```html
+<!-- Wrong: h4 chosen because it's smaller -->
+<h4 class="card-title">Product Name</h4>
+<!-- Right: appropriate level with visual override -->
+<h3 class="card-title u-heading-s">Product Name</h3>
+```
+### Missing Defaults
+```jsx
+// Dangerous: undefined heading level
+function Card({ title, headingLevel }) {
+  const Heading = `h${headingLevel}`; // h undefined if not passed
+  return <Heading>{title}</Heading>;
+}
+// Safe: always has a valid level
+function Card({ title, headingLevel = 3 }) {
+  const Heading = `h${headingLevel}`;
+  return <Heading>{title}</Heading>;
+}
+```