@lion/ui 0.25.0 → 0.26.0

package/docs/fundamentals/node-tools/rocket-preset-extend-lion-docs/overview.md

@@ -1,298 +0,0 @@
----
-parts:
-  - Overview
-  - Extend Docs
-  - Node Tools
-title: 'Overview'
-eleventyNavigation:
-  key: Node Tools >> Extend Docs >> Overview
-  title: Overview
-  order: 10
-  parent: Node Tools >> Extend Docs
----
-
-# Overview
-
-When maintaining your own extension layer of lion you most likely want to maintain a similar documentation.
-Copying and rewriting imports/tags the markdown files works but also means that whenever something change you need copy and rewrite again.
-
-To do this automatically you can use this preset for [rocket](https://rocket.modern-web.dev/).
-
-## Features
-
-- Import lion documentation and adjust it using [remark-extend](https://github.com/ing-bank/lion/blob/9575386e5fb419f7dbd3b893be4c4ce7925bcb2e/docs/fundamentals/node-tools/remark-extend/overview.md)
-- Renames named imports and all it's usage
-- Adjusts import paths
-- Replace tags in template literals
-
-## Installation
-
-```bash
-npm i -D rocket-preset-extend-lion-docs
-```
-
-👉 _rocket.config.js_
-
-```js
-import { rocketLaunch } from '@rocket/launch';
-import { extendLionDocs } from 'rocket-preset-extend-lion-docs';
-
-const extendLionDocsInstance = await extendLionDocs({
-  classPrefix: 'Wolf',
-  classBareImport: '@wolf/',
-  tagPrefix: 'wolf-',
-  tagBareImport: '@wolf/',
-});
-
-export default {
-  presets: [rocketLaunch(), extendLionDocsInstance],
-};
-```
-
-## Reusing documentation
-
-To take an existing documentation you can "import" it using [remark-extend](https://github.com/ing-bank/lion/blob/9575386e5fb419f7dbd3b893be4c4ce7925bcb2e/docs/fundamentals/node-tools/remark-extend/overview.md).
-
-As an example you can create `docs/components/tabs/overview.md`.
-
-In it you do
-
-- write a headline
-- use importSmallBlockContent to reuse content from lion
-- add your own installation instruction
-
-````md
-# Tabs >> Overview ||10
-
-```js ::importSmallBlockContent('@lion/ui/tabs/docs/overview.md', '# Tabs >> Overview ||10.js')
-
-```
-
-## Installation
-
-```bash
-npm i --save @wolf/tabs
-```
-
-```js
-import { WolfTabs } from '@wolf/tabs';
-```
-````
-
-## How does it work
-
-1. `importSmallBlockContent`` will import the content from lion
-2. all code blocks will then be precessed to use `@wolf` instead of `@lion`
-3. all links which are absolute to github will be processed to be local links
-
-as an example this is a part of the lion docs for tabs
-
-````md
-```js script
-import { LitElement, html } from '@mdjs/mdjs-preview';
-import '@lion/ui/define/lion-tabs.js';
-```
-
-```js preview-story
-export const main = () => html`
-  <lion-tabs>
-    <button slot="tab">Info</button>
-    <p slot="panel">Info page with lots of information about us.</p>
-    <button slot="tab">Work</button>
-    <p slot="panel">Work page that showcases our work.</p>
-  </lion-tabs>
-`;
-```
-````
-
-After all replacements the output that will be used for markdown rendering will be
-
-````md
-# Tabs >> Overview ||10
-
-```js script
-import { LitElement, html } from '@wolf/core';
-import '@wolf/tabs/define';
-```
-
-```js preview-story
-export const main = () => html`
-  <wolf-tabs>
-    <button slot="tab">Info</button>
-    <p slot="panel">Info page with lots of information about us.</p>
-    <button slot="tab">Work</button>
-    <p slot="panel">Work page that showcases our work.</p>
-  </wolf-tabs>
-`;
-```
-
-## Installation
-
-```bash
-npm i --save @wolf/tabs
-```
-
-```js
-import { WolfTabs } from '@wolf/tabs';
-```
-````
-
-Doing so means you can focus on writing what is specific to your design system extension and you don't need to rewrite all the examples and explanations of lion but you can import them while still using your components.
-
-## Use with a monorepo
-
-The above setup assumes that you have the same "system" of exports in `@wolf` as we have in `@lion`.
-
-So your users are able to do
-
-```js
-// provide classes as side effect free imports
-import { WolfTabs } from '@wolf/tabs';
-// register web components via `/define`
-import '@wolf/tabs/define';
-```
-
-This means you need to have to define the following package entry points for you tabs extension.
-
-👉 _tabs/package.json_
-
-```json
-"exports": {
-  ".": "./src/index.js",
-  "./define": "./src/define/tabs.js",
-}
-```
-
-## Use as a single repo
-
-Often its easier for your users to have one package to work with instead of a big list of individual packages.
-If you are distributing one package then your exports/imports will be different.
-
-So your users are able to do
-
-```js
-// provide classes as side effect free imports
-import { WolfTabs } from 'wolf-web/tabs';
-// register web components via `/define`
-import 'wolf-web/tabs/define';
-```
-
-👉 _package.json_
-
-```json
-"exports": {
-  ".": "./index.js",
-  "./tabs/define": "./define/tabs.js",
-}
-```
-
-The configuration for that is
-
-👉 _rocket.config.js_
-
-```js
-import { rocketLaunch } from '@rocket/launch';
-import { extendLionDocs } from 'rocket-preset-extend-lion-docs';
-
-const extendLionDocsInstance = await extendLionDocs({
-  classPrefix: 'Wolf',
-  classBareImport: 'wolf-web/',
-  tagPrefix: 'wolf-',
-  tagBareImport: 'wolf-web/',
-});
-
-export default {
-  presets: [rocketLaunch(), extendLionDocsInstance],
-};
-```
-
-## Do not distribute side effects
-
-When distributing you may choose to stay side effect free. This means no definitions of custom elements. You may want to do this to "force" usage of a scoped registry in order to support multiple mayor version of a component in a single application. We would recommend [Scoped Elements](https://open-wc.org/docs/development/scoped-elements/) for that.
-
-So your users are able to do
-
-```js
-// provide classes as side effect free imports
-import { WolfTabs } from 'wolf-web/tabs';
-// NOTE: there no way to import a definition as a user
-```
-
-For demos it's still useful/needed to have those definitions. To have them but not exposing them you can use private imports which are only available to the package itself. This feature is called [Subpath imports](https://nodejs.org/dist/latest-v16.x/docs/api/packages.html#packages_subpath_imports) in node.
-
-To enable it you can set the following settings
-
-👉 _rocket.config.js_
-
-```js
-import { rocketLaunch } from '@rocket/launch';
-import { extendLionDocs } from 'rocket-preset-extend-lion-docs';
-
-const extendLionDocsInstance = await extendLionDocs({
-  classPrefix: 'Wolf',
-  classBareImport: 'wolf-web/',
-  tagPrefix: 'wolf-',
-  tagBareImport: '#',
-});
-
-export default {
-  presets: [rocketLaunch(), extendLionDocsInstance],
-};
-```
-
-This rewrites the custom element definition side effects to
-
-```js
-// from
-import '@lion/ui/define/lion-tabs.js';
-
-// to
-import '#tabs/define';
-```
-
-In order for such imports to work you need to define them
-
-👉 _package.json_
-
-```json
-"imports": {
-  "#tabs/define": "./__element-definitions/wolf-tabs.js",
-}
-```
-
-## Global replacements
-
-Sometimes you need a bit more power when extending lion documentation.
-For instance, you're extending repository has a different folder structure. Instead of putting your systems
-documentation inside 'systems', you want to put it in 'web-systems'.
-
-The configuration for that is (see `globalReplaceFunction`):
-
-👉 _rocket.config.js_
-
-```js
-import { rocketLaunch } from '@rocket/launch';
-import { extendLionDocs } from 'rocket-preset-extend-lion-docs';
-
-const extendLionDocsInstance = await extendLionDocs({
-  classPrefix: 'Wolf',
-  classBareImport: 'wolf-web/',
-  tagPrefix: 'wolf-',
-  tagBareImport: 'wolf-web/',
-  globalReplaceFunction: node => {
-    if (node.type === 'link') {
-      // All internal links to '/systems/' (like '(../../fundamentals/systems/overlays/configuration.md)'),
-      // will be changed into '/web-systems/' ('(../../fundamentals/web-systems/overlays/configuration.md)').
-      node.url = node.url.replace(/\systems\/g, '/web-systems/');
-    }
-    return node;
-  }
-});
-
-export default {
-  presets: [rocketLaunch(), extendLionDocsInstance],
-};
-```
-
-Remember: with great power comes great responsibility, so make sure your replacements do not introduce unintended
-effects.

package/docs/fundamentals/rationales/TypeScript.md

@@ -1,123 +0,0 @@
----
-parts:
-  - TypeScript
-  - Rationales
-title: 'TypeScript'
-eleventyNavigation:
-  key: Rationales >> TypeScript
-  title: TypeScript
-  order: 30
-  parent: Rationales
----
-
-# TypeScript
-
-[TypeScript](https://www.typescriptlang.org) is superset of JavaScript and a popular tool for getting strongly typed syntax and better autocompletion in JavaScript.
-
-We've ensured that the entire Lion library is typed so that you can use it in TypeScript, but there are some caveats.
-
-## Why JSDoc?
-
-Lion uses [JSDoc](https://jsdoc.app/) for type annotations instead of native TypeScript files. This approach offers several advantages:
-
-**No Compilation Step**: JSDoc allows us to maintain a pure JavaScript codebase while still providing comprehensive type information. This eliminates the need for a TypeScript compilation step in our build process, keeping our development workflow simple, fast and robust.
-
-**Runtime JavaScript**: Since our source files remain `.js`, they can be executed directly by JavaScript engines without any transformation. This is particularly valuable for debugging, as you're working with the actual code that runs in production.
-
-**Universal Compatibility**: JSDoc annotations are just comments, so they don't affect runtime behavior and are compatible with any JavaScript environment. Libraries and tools that don't understand TypeScript can still consume Lion packages without issues.
-
-**Gradual Adoption**: Teams can benefit from Lion's type information regardless of whether they use TypeScript, plain JavaScript with JSDoc, or other type checking tools. The types are there when you need them, invisible when you don't.
-
-**TypeScript Integration**: Despite using JSDoc, we still get full TypeScript integration. The TypeScript compiler can read JSDoc annotations and generate proper `.d.ts` files, giving consumers the same autocomplete and type checking experience as native TypeScript packages.
-
-## Mixins
-
-In Lion, we rely heavily on [Mixins](https://lit.dev/docs/composition/mixins/#mixin-basics) as a pattern for abstracting certain behaviors and properties into implementable interfaces.
-Since JavaScript has a one-dimensional inheritance chain, inheriting from multiple ancestors has always been tricky, the Mixin pattern is used to get around that.
-
-Here's the thing, Mixins have been notoriously difficult to type properly in TypeScript and in addition, we did not feel happy about adding an adhoc compilation step in our developer workflow. Therefore, we opted for typing our code with [JSDoc](https://jsdoc.app/) and using TypeScript to lint our types and generate type definition files.
-
-Consuming Lion as `.js` typed by JSDoc is not much different from consuming it as when they were `.ts` files, but due to Mixins being very tricky to type, we've had to use `@ts-ignore` in a couple of places, most importantly, in many of our mixins.
-
-For context, here's a [thread on the issue](https://github.com/microsoft/TypeScript/issues/36821) of inheritance type constraints in mixins, where a user suggested allowing to ignore the rule that causes problems.
-This suggestion was declined and in [this comment](https://github.com/microsoft/TypeScript/issues/36821#issuecomment-588375051), Ryan Cavanaugh explained that using `@ts-ignore` is the right way to get around the limitation here.
-As a user of Lion this means that because we've got `@ts-ignore`s in our source code, you may get type errors that originate from Lion, and there's nothing we can do about that, TypeScript's stance is that sometimes rules are too conservative, and ignoring them is the correct answer.
-
-In order to ignore type issues coming from Lion, please use the [skipLibCheck](https://www.typescriptlang.org/tsconfig#skipLibCheck) option in your `ts.config.json`, this will ignore issues that aren't coming from your code.
-
-## Export Maps and Type Resolution
-
-Lion uses [package.json export maps](https://nodejs.org/api/packages.html#exports) to provide proper module resolution and type definitions. The export map ensures that when you import from Lion packages, TypeScript can correctly resolve both the JavaScript modules and their corresponding type definitions.
-
-The export map works by defining explicit entry points for each package, mapping import paths to their actual file locations. For types, this means that when you import `@lion/ui/button.js`, TypeScript knows to look for the corresponding type definitions in the `dist-types` directory.
-
-## Subclass extension points and Lion 0.22
-
-`_focusableNode` is a protected getter in `FocusMixin`: subclasses can override it or
-access it through `this` and `super`. It is not a public DOM-query API. Lion 0.22 made
-the `LionField` and `LionListbox` overrides protected too; their earlier emitted
-declarations exposed them publicly, despite the protected mixin contract.
-
-For focusing a control, the supported public API is `control.focus()`, which delegates
-to its focusable node; `control.blur()` delegates similarly. This is not a replacement
-for every direct node access: event listeners, DOM inspection, focus options, and
-access to another component's internals need a separate downstream review. Subclass
-configuration remains supported without making the getter public.
-
-`slots` is a getter, both at runtime and in `SlotHost`. On TypeScript 4.7, intersecting
-a subclass constructor with another `Constructor<SlotHost>` can collapse the inherited
-getter into a property and reject a further getter override with `TS2611`. `SlotMixin`
-preserves the superclass type when its host is already present, matching its runtime
-deduplication; this allows extending `SlotMixin(LionSelectRich)` without that duplicate.
-
-Its overloads preserve an already-slotted base and describe a newly applied host
-separately. Unlike an unresolved conditional return type, this keeps a generic
-constructor recognizable when composing `ValidateMixin(SlotMixin(base))`. The
-newly applied host has one combined `LitElement & SlotHost` prototype rather than
-two intersected prototype declarations; base constructors and their static members
-remain part of the return type.
-
-`LionOption.styles` returns Lit's `CSSResultArray`, including nested style arrays.
-Subclasses may therefore return `[super.styles, additionalStyles]`, as supported
-by Lit at runtime, without flattening the inherited array solely for type checking.
-
-Downstream mixin signatures must also avoid reintroducing an already inherited
-`SlotHost`. For a mixin that **requires** a slotted base and only adds `FieldHost`
-members, the signature can retain those members without redeclaring the slot host:
-
-```ts
-import type { Constructor } from '@open-wc/dedupe-mixin';
-import type { LitElement } from 'lit';
-import type { SlotHost } from '@lion/ui/types/core.js';
-
-declare class FieldHost {
-  extraFieldOption: boolean;
-}
-
-declare function FieldMixin<T extends Constructor<LitElement & SlotHost>>(
-  base: T,
-): T & Constructor<FieldHost>;
-```
-
-Do not simply remove `SlotHost` from a mixin that must add slot support to an unslotted
-base, or drop other host members from its return type. Its signature must describe the
-actual composition. Neither `skipLibCheck` nor suppressing a downstream getter error
-corrects that signature.
-
-The consumer declaration gate (`npm run types-check-consumer --workspace @lion/ui`)
-checks the copied package's entry points, subclass extensions and JSDoc-typed generic
-mixin composition on the current compiler, plus the extension fixtures on pinned
-TypeScript 4.7.4. The older compiler is
-isolated in the private `test/typescript-legacy` workspace so it cannot replace the
-compiler used to build Lion.
-
-## Type correction for JSDoc (no longer needed)
-
-Because Lion types its JavaScript with JSDoc rather than `.ts` files, older TypeScript
-versions emitted declaration paths that were not portable: `lit-element/lit-element.js`
-where the declaration really came from `lit`, and internal `node_modules/@open-wc/...`
-references that no consumer could resolve.
-
-A post-build script (`scripts/types-correct-after-build.js`) rewrote those paths after
-every build. **TypeScript 7 emits the correct specifiers itself**, so that script has been
-deleted: the `types` target in `packages/ui` is now a plain `tsc --build`.

package/docs/fundamentals/rationales/accessibility.md

@@ -1,40 +0,0 @@
----
-parts:
-  - Accessibility
-  - Rationales
-title: 'Accessibility'
-eleventyNavigation:
-  key: Rationales >> Accessibility
-  title: Accessibility
-  order: 5
-  parent: Rationales
----
-
-# Accessibility
-
-In Lion accessibility is a first class citizen. That means accessibility is never an afterthought.
-
-Whenever we create a component, we do some thorough research first. Experience from past web component libraries learned us that when accessibility was dealt with in hindsight, a lot of concessions needed to be made. It made us want to go back to the drawing board. Lion was started with this 'fresh drawing board'.
-In general, we try to leverage out of the box accessible platform solutions as much as possible. When no platform solutions are available, we try to map our components to [aria patterns and widgets as defined by W3C](https://www.w3.org/WAI/ARIA/apg/) where possible.
-Building accessible components takes a lot of time, practice and knowledge about screen reader and browser implementations. Then, it takes many testing iterations to finetune a component.
-
-More on this topic can be found in the online panel discussion [Web Components, Design Systems and Accessibility](https://www.youtube.com/watch?v=xz8yRVJMP2k&t=1190s). The discussion also contains a [dedicated section about accessible form components](https://www.youtube.com/watch?v=xz8yRVJMP2k&t=1917s)
-
-## Shadow roots and accessibility
-
-Since our components and applications consist of multiple shadow roots that need to be able to reference each other, architecting accessible components takes extra strategy and planning.
-A practical example: all form controls inside a fieldset need to be able to lay accessible id relations to their parent (the fieldset). In other words, id relations should be cross component (which usually means cross shadow root). Scenarios like these require consistent architecture, allowing all form components to be interoperable. In general, light dom needs to be leveraged until a solution for cross root aria is available. For a deeper understanding of the topic, be sure to view these [slides about cross root aria](https://github.com/home/runner/work/lion/lion/prev/_merged_assets/_static/crossRootAriaLion.pdf).
-
-## Some details about the form system
-
-A huge part of Lion consists of its form system and components.
-
-This [presentation about accessible form components](https://github.com/home/runner/work/lion/lion/prev/_merged_assets/_static/theoryOfFormsLion.pdf) explains how accesibility is built-in in all form components.
-
-## SlotMixin
-
-Internally, we delegate all intricacies involved in managing light dom to SlotMixin.
-SlotMixin automatically mediates between light dom provided by the user ('public slots') and light dom provided by the component author ('private slots').
-Also, SlotMixin allows to hook into the reactive update loop of LitElement (automatically rerendering on property changes) and it automatically respects
-the scoped registry belonging to the shadow root.
-More details about SlotMixin can be found in the [SlotMixin documentation](https://github.com/ing-bank/lion/blob/9575386e5fb419f7dbd3b893be4c4ce7925bcb2e/docs/fundamentals/systems/core/SlotMixin.md)

package/docs/fundamentals/rationales/index.md

@@ -1,11 +0,0 @@
----
-parts:
-  - Rationales
-title: Rationales
-eleventyNavigation:
-  key: Rationales
-  title: Rationales
-  order: 50
----
-
-# Rationales