diff --git a/packages/web/CONTRIBUTING.md b/packages/web/CONTRIBUTING.md index 2304efa8d7..d2ee0fc3d5 100644 --- a/packages/web/CONTRIBUTING.md +++ b/packages/web/CONTRIBUTING.md @@ -14,7 +14,7 @@ This is an example of a typical file structure of a component: -``` +```txt ├── src ├── scss │ └── components @@ -60,7 +60,7 @@ Similarly, component's tools serve as a storage of component-scoped: ## Linking Design Tokens -Components can (and should!) reuse Spirit [design tokens]. +Components can (and should!) reuse Spirit [design tokens][design-tokens]. Component's theme properties can be linked to design tokens. This way, the appearance of individual components is always unified and coherent: **anytime @@ -71,7 +71,7 @@ discussion between Spirit developers and designers. Linking component properties to design tokens needs to be done carefully **in order for the design to work as a system.** -Default Spirit design tokens live in the [`spirit-design-tokens`] package. +Default Spirit design tokens live in the [`spirit-design-tokens`][design-tokens] package. Products may define their own design tokens as long as they preserve the same structure and naming. @@ -85,7 +85,7 @@ the [`@tokens` API][tokens-api] with From the implementation point of view, design tokens are Sass variables organized in Sass modules. Within component styles, Sass modules with design tokens are referred to just by filename. However, because the modules do not -exist in the place they are called in (the [`spirit-design-tokens`] package is +exist in the place they are called in (the [`spirit-design-tokens`][design-tokens] package is stored in `node_modules`), the correct load path for the desired set of design tokens must be [provided on build time][configuring-load-path]. This is the only way how Sass modules can be affected from outside, without giving in their @@ -193,7 +193,7 @@ great portion of encapsulation, traceability, and more. Does @use behave the same way as @import? In most situations, no. Most importantly, while `@import` loads everything into -global context, `@use` is scoped and works more like `import` in [ES modules]. +global context, `@use` is scoped and works more like `import` in [ES modules][es-modules]. @@ -217,12 +217,11 @@ To avoid conflicts, we need a convention to distinguish situations when somethin - `id` attribute can be used by **JS only**. -[design tokens]: https://github.com/lmc-eu/spirit-design-system/tree/main/packages/design-tokens -[`spirit-design-tokens`]: https://github.com/lmc-eu/spirit-design-system/tree/main/packages/design-tokens +[design-tokens]: https://github.com/lmc-eu/spirit-design-system/tree/main/packages/design-tokens [tokens-api]: https://github.com/lmc-eu/spirit-design-system/tree/main/packages/design-tokens#tokens-api [configuring-load-path]: https://github.com/lmc-eu/spirit-design-system/tree/main/packages/design-tokens#configuring-load-path [rebranding]: https://github.com/lmc-eu/spirit-design-system/tree/main/packages/web#rebranding [design-tokens-faq]: https://github.com/lmc-eu/spirit-design-system/tree/main/packages/design-tokens#faq [sass-modules]: https://sass-lang.com/blog/the-module-system-is-launched -[es modules]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Modules +[es-modules]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Modules [sass-true]: https://github.com/oddbird/true diff --git a/packages/web/README.md b/packages/web/README.md index 17ea959d8d..1c369f96d2 100644 --- a/packages/web/README.md +++ b/packages/web/README.md @@ -1,5 +1,10 @@ + + + # @lmc-eu/spirit-web + + > CSS implementation of Spirit Design System. ## Install @@ -73,7 +78,7 @@ module.exports = { Some components require JavaScript plugins for their full functionality. You can use individual modules or compiled bundle. -#### Individual or compiled +#### Individual or Compiled Plugins can be included individually as an EcmaScript module (using `import { } from '@lmc-eu/spirit-web'`, see [Using Spirit Web as a module](#using-spirit-web-as-a-module)), or all at once using `js/{cjs|esm|bundle}/spirit-web.js` or the minified `js/{cjs|esm|bundle}/spirit-web.min.js` (do not include both), all files are UMD ready. @@ -83,7 +88,7 @@ Plugins can be included individually as an EcmaScript module (using `import {

``` -#### Data attributes +#### Data Attributes Nearly all Spirit-Web plugins can be enabled and configured through HTML alone with data attributes (our preferred way of using JavaScript functionality). Be sure to only use one set of data attributes on a single element (e.g., you cannot trigger a tooltip and modal from the same button.). @@ -136,7 +141,7 @@ var modal = new Modal(myModalEl); // initialized with defaults If you’d like to get a particular plugin instance, each plugin exposes a `getInstance` method. -#### CSS selectors in constructors +#### CSS Selectors in Constructors You can also use a CSS selector as the first argument instead of a DOM element to initialize the plugin. Currently the element for the plugin is found by the `querySelector` method since our plugins support a single element only. @@ -171,7 +176,7 @@ Learn more in the [`spirit-design-tokens` docs][rebranding]. Start local development server with `yarn start` to get started. You will get the live preview of all components and plugins in your browser. Just get dirty and change something and you will see the changes live. -The dev-stack is based on [Vite]. +The dev-stack is based on [Vite][vite]. ## Deprecations @@ -186,7 +191,7 @@ Check your browser console to see if you are using any of the deprecated functio ## Examples -👀 See [examples] for a live demo. +👀 See [examples][examples] for a live demo. ## License diff --git a/packages/web/src/scss/components/Accordion/README.md b/packages/web/src/scss/components/Accordion/README.md index fcf9d5a8de..a92930b804 100644 --- a/packages/web/src/scss/components/Accordion/README.md +++ b/packages/web/src/scss/components/Accordion/README.md @@ -14,7 +14,7 @@ Building blocks: - Collapse - Accordion content -### Accordion +### Accordion Component Common wrapper for all items: @@ -172,7 +172,7 @@ When you put it all together: ``` -### Open only one item at a time +### Open Inly One Item at a Time Link individual **Collapse items** to their **Accordion parent** via `data-spirit-parent` attribute to allow just a single item being open at a time. diff --git a/packages/web/src/scss/components/Breadcrumbs/README.md b/packages/web/src/scss/components/Breadcrumbs/README.md index 1541456c2e..7f32b67929 100644 --- a/packages/web/src/scss/components/Breadcrumbs/README.md +++ b/packages/web/src/scss/components/Breadcrumbs/README.md @@ -38,7 +38,7 @@ Shows where the user is within the app hierarchy. ``` -### Dealing with long titles +### Dealing with Long Titles When you need to shorten the title of the Breadcrumbs item you can use a helper class `text-truncate` with defined width. diff --git a/packages/web/src/scss/components/Checkbox/README.md b/packages/web/src/scss/components/Checkbox/README.md index e778268d45..fbb77113d1 100644 --- a/packages/web/src/scss/components/Checkbox/README.md +++ b/packages/web/src/scss/components/Checkbox/README.md @@ -1,6 +1,6 @@ # Checkbox -## Basic usage: +## Basic Usage ```html ``` -## Required input: +## Required Input ```html ``` -## Validation State with Validation Text: +## Validation State with Validation Text See Validation state [dictionary][dictionary-validation]. @@ -47,7 +47,7 @@ See Validation state [dictionary][dictionary-validation]. ``` -## Hidden label: +## Hidden Label ```html ``` -## Helper Text: +## Helper Text ```html ``` -## Disabled state: +## Disabled State ```html ``` -## As an Item: +## As an Item ```html

@@ -42,7 +42,7 @@
``` -## Usage with top-end align +## Usage with Top End Align ```html
@@ -84,7 +84,7 @@
``` -## Usage with disabled autoclose +## Usage with Disabled Autoclose ```html
@@ -127,7 +127,7 @@
``` -## Usage with full width mode `all` +## Usage with Full Width Mode All ```html
@@ -174,7 +174,7 @@
``` -## Usage with full width mode `mobile-only` +## Usage with Full Width Mode Mobile-Only ```html
@@ -221,7 +221,7 @@
``` -## Usage with [Item] component +## Usage with [Item][item] Component ```html
@@ -256,7 +256,7 @@ a value of data attribute `data-spirit-placement`, e.g. `data-spirit-placement=" There are two options here. Use the trigger element as an anchor or wrap the menu together with the trigger into a `.Dropdown` class. -### Dropdown trigger +### Dropdown Trigger | Attribute | Type | Default | Required | Description | | ----------------------- | -------- | ------- | -------- | -------------------------------------------------------------------------------------------------------------- | @@ -267,9 +267,9 @@ There are two options here. Use the trigger element as an anchor or wrap the men ## DropdownPopover -| Attribute | Type | Default | Required | Description | -| --------------------------- | --------------------------------- | ------- | -------- | --------------- | -| `data-spirit-fullwidthmode` | [`off` \| `mobile-only` \| `all`] | — | ✕ | Full-width mode | +| Attribute | Type | Default | Required | Description | +| --------------------------- | ---------------------------------- | ------- | -------- | --------------- | +| `data-spirit-fullwidthmode` | \[`off` \| `mobile-only` \| `all`] | — | ✕ | Full-width mode | ## JavaScript API diff --git a/packages/web/src/scss/components/FieldGroup/README.md b/packages/web/src/scss/components/FieldGroup/README.md index 461d26d860..a35efb3ece 100644 --- a/packages/web/src/scss/components/FieldGroup/README.md +++ b/packages/web/src/scss/components/FieldGroup/README.md @@ -161,7 +161,7 @@ To render validation text as a list, use ` ``` -## Advanced usage +## Advanced Usage Usage with combination of spacing and dividers: diff --git a/packages/web/src/scss/components/TextArea/README.md b/packages/web/src/scss/components/TextArea/README.md index 922d05420e..9a73a42ccd 100644 --- a/packages/web/src/scss/components/TextArea/README.md +++ b/packages/web/src/scss/components/TextArea/README.md @@ -52,7 +52,7 @@ Helper text: There are several ways to adjust the textarea width: -### `rows` Attribute +### Rows Attribute The number of visible text lines for the control. Supported values are positive integers from `3` up. @@ -118,7 +118,7 @@ When implementing client-side form validation, use JS interaction state classes (`has-success`, `has-warning`, `has-danger`) on the wrapping `
` element and render validation texts in a `
` or `
    ` with `data-spirit-element="validation_text"` attribute. This way your JS remains disconnected from CSS that may or may not be -[prefixed]. +[prefixed][prefixed]. **Remember this approach is only valid for vanilla JS implementation. React components mix CSS with JS by design and handle prefixes their own way.** diff --git a/packages/web/src/scss/components/TextField/README.md b/packages/web/src/scss/components/TextField/README.md index 4b010b64e5..1a289d6dfa 100644 --- a/packages/web/src/scss/components/TextField/README.md +++ b/packages/web/src/scss/components/TextField/README.md @@ -66,7 +66,7 @@ Helper Text:
``` -## Supported `type` Values +## Supported Type Attribute Values TextField supports the following input types: @@ -85,7 +85,7 @@ input field will not be consistent across platforms/browsers. There are several ways to adjust the input width: -### `size` Attribute +### Size Attribute The `size` attribute is supported on inputs of the following types: `email`, `password`, `tel`, `text`, `url`. @@ -229,7 +229,7 @@ When implementing client-side form validation, use JS interaction state classes (`has-success`, `has-warning`, `has-danger`) on the wrapping `
` element and render validation texts in a `
` or `
    ` with `data-spirit-element="validation_text"` attribute. This way your JS remains disconnected from CSS that may or may not be -[prefixed]. +[prefixed][prefixed]. **Remember this approach is only valid for vanilla JS implementation. React components mix CSS with JS by design and handle prefixes their own way.** @@ -285,3 +285,4 @@ JS interaction class when controlled by JavaScript: [prefixed]: https://github.com/lmc-eu/spirit-design-system/blob/main/packages/web/README.md#prefixing-css-class-names [dictionary-validation]: https://github.com/lmc-eu/spirit-design-system/blob/main/docs/DICTIONARIES.md#validation +[web-readme]: https://github.com/lmc-eu/spirit-design-system/blob/main/packages/web/README.md diff --git a/packages/web/src/scss/components/Toast/README.md b/packages/web/src/scss/components/Toast/README.md index 9f368f86df..85f4fc2adf 100644 --- a/packages/web/src/scss/components/Toast/README.md +++ b/packages/web/src/scss/components/Toast/README.md @@ -23,7 +23,7 @@ Please consult the [main README][web-readme] for how to include JavaScript plugi Or, feel free to write the controlling script yourself. -## Toast +## Toast Component The Toast component is a container responsible for positioning the [ToastBar](#toastbar) component. It is capable of handling even multiple toast messages at once, stacking them in a [queue](#toast-queue). diff --git a/packages/web/src/scss/components/Tooltip/README.md b/packages/web/src/scss/components/Tooltip/README.md index c3e000848c..ec7856bdf0 100644 --- a/packages/web/src/scss/components/Tooltip/README.md +++ b/packages/web/src/scss/components/Tooltip/README.md @@ -107,20 +107,6 @@ automatically, including smart position updates to ensure Tooltip visibility, we recommend involving an external library designed specifically for this purpose. -### Placement - -```html -
    - -
    - Hello there! - -
    -
    -``` - ### Arrow When controlling Tooltip arrow with JavaScript, set `data-spirit-element="arrow"` @@ -191,14 +177,14 @@ works and to get an idea of all possible cases you may need to cover. | Attribute | Type | Default | Required | Description | | ----------------------------------------------- | -------------------------------------------- | -------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `data-spirit-enable-flipping-cross-axis` | [true \| false] | true | ✕ | Enables flipping on the [cross axis][floating-ui-flip-cross-axis], the axis perpendicular to main axis. For example `top-end` can be flipped to the `top-start`. | -| `data-spirit-enable-flipping` | [true \| false] | true | ✕ | Enables [flipping[floating-ui-flip] of the element’s placement when it starts to overflow its boundary area. For example `top` can be flipped to `bottom`. | -| `data-spirit-enable-shifting` | [true \| false] | true | ✕ | Enables [shifting][floating-ui-shift] of the element to keep it inside the boundary area by adjusting its position. | -| `data-spirit-enable-sizing` | [true \| false] | true | ✕ | Enables [sizing][floating-ui-size] of the element to keep it inside the boundary area by setting the max width. | -| `data-spirit-flip-fallback-axis-side-direction` | ["none" \| "start" \| "end" ] | "none" | ✕ | Whether to allow [fallback to the opposite axis][floating-ui-flip-fallback-axis-side-direction] if no placements along the preferred placement axis fit, and if so, which side direction along that axis to choose. If necessary, it will fallback to the other direction. | +| `data-spirit-enable-flipping-cross-axis` | \[true \| false] | true | ✕ | Enables flipping on the [cross axis][floating-ui-flip-cross-axis], the axis perpendicular to main axis. For example `top-end` can be flipped to the `top-start`. | +| `data-spirit-enable-flipping` | \[true \| false] | true | ✕ | Enables [flipping][floating-ui-flip] of the element’s placement when it starts to overflow its boundary area. For example `top` can be flipped to `bottom`. | +| `data-spirit-enable-shifting` | \[true \| false] | true | ✕ | Enables [shifting][floating-ui-shift] of the element to keep it inside the boundary area by adjusting its position. | +| `data-spirit-enable-sizing` | \[true \| false] | true | ✕ | Enables [sizing][floating-ui-size] of the element to keep it inside the boundary area by setting the max width. | +| `data-spirit-flip-fallback-axis-side-direction` | \["none" \| "start" \| "end" ] | "none" | ✕ | Whether to allow [fallback to the opposite axis][floating-ui-flip-fallback-axis-side-direction] if no placements along the preferred placement axis fit, and if so, which side direction along that axis to choose. If necessary, it will fallback to the other direction. | | `data-spirit-flip-fallback-placements` | string | - | ✕ | This describes a list of [explicit placements][floating-ui-flip-fallback-placements] to try if the initial placement doesn’t fit on the axes in which overflow is checked. For example you can set `"top, right, bottom"` | | `data-spirit-placement` | [Placement Dictionary][dictionary-placement] | "bottom" | ✕ | Placement of tooltip | -| `data-spirit-trigger` | ["click" \| "hover" \| "manual"] | "click, hover" | ✕ | How tooltip is triggered: `click`, `hover`, `manual`. You may pass multiple triggers; separate them with a comma. If you pass `manual`, no event listener will be added, and you should provide your own toggle solution. | +| `data-spirit-trigger` | \["click" \| "hover" \| "manual"] | "click, hover" | ✕ | How tooltip is triggered: `click`, `hover`, `manual`. You may pass multiple triggers; separate them with a comma. If you pass `manual`, no event listener will be added, and you should provide your own toggle solution. | 👆 All the attributes mentioned above can be also set as an object in the `config` attribute, like this: `data-spirit-config='{"flip": "true", "flipFallbackPlacements": "top, right, bottom"}'`. Please note that this configuration has lower priority than individual attributes and will be overwritten by them. @@ -241,12 +227,10 @@ tooltip.hide(); ``` [dictionary-placement]: https://github.com/lmc-eu/spirit-design-system/tree/main/docs/DICTIONARIES.md#placement -[example]: https://spirit-design-system-demo.netlify.app/src/scss/components/tooltip/#advanced-positioning [floating-ui-flip-cross-axis]: https://floating-ui.com/docs/flip#crossaxis -[floating-ui-flip-floating-ui-flip-fallback-axis-side-direction]: https://floating-ui.com/docs/flip#fallbackaxissidedirection +[floating-ui-flip-fallback-axis-side-direction]: https://floating-ui.com/docs/flip#fallbackaxissidedirection [floating-ui-flip-fallback-placements]: https://floating-ui.com/docs/flip#fallbackplacements [floating-ui-flip]: https://floating-ui.com/docs/flip [floating-ui-shift]: https://floating-ui.com/docs/shift [floating-ui-size]: https://floating-ui.com/docs/size [floating-ui]: https://floating-ui.com -[readme-feature-flags]: https://github.com/lmc-eu/spirit-design-system/blob/main/packages/web/README.md#feature-flags diff --git a/packages/web/src/scss/components/UNSTABLE_EmptyState/README.md b/packages/web/src/scss/components/UNSTABLE_EmptyState/README.md index 7f32e8412a..6c312ab62c 100644 --- a/packages/web/src/scss/components/UNSTABLE_EmptyState/README.md +++ b/packages/web/src/scss/components/UNSTABLE_EmptyState/README.md @@ -8,9 +8,11 @@ EmptyState component should be included at the error pages or empty state pages EmptyState component is a composition of the following components: - [UNSTABLE_EmptyState](#unstable-emptystate) - - [UNSTABLE_EmptyStateSection](#unstable-emptystatesection) +- [UNSTABLE_EmptyStateSection](#unstable-emptystatesection) -## UNSTABLE EmptyState +## Component Composition + +### UNSTABLE_EmptyState The `UNSTABLE_EmptyState` component is a main container responsible for positioning the [UNSTABLE_EmptyStateSection](#unstable-emptystatesection) components or content. @@ -22,7 +24,7 @@ The `UNSTABLE_EmptyState` component is a main container responsible for position This component is based on the [Stack][stack] component and accepts all its variants. For more information about `Stack` usage options, see the [Stack documentation][stack]. -## UNSTABLE EmptyStateSection +### UNSTABLE_EmptyStateSection The `UNSTABLE_EmptyStateSection` component is a container for the content of each section. @@ -34,9 +36,7 @@ The `UNSTABLE_EmptyStateSection` component is a container for the content of eac This component is based on the [Stack][stack] component and accepts all its variants. For more information about `Stack` usage options, see the [Stack documentation][stack]. -[stack]: https://github.com/lmc-eu/spirit-design-system/blob/dependencies/major-monorepo-storybook/packages/web/src/scss/components/Stack/README.md - -## Full Example +### Full Example ```html
    @@ -54,3 +54,5 @@ This component is based on the [Stack][stack] component and accepts all its vari
    Link to something
    ``` + +[stack]: https://github.com/lmc-eu/spirit-design-system/blob/dependencies/major-monorepo-storybook/packages/web/src/scss/components/Stack/README.md diff --git a/packages/web/src/scss/components/UNSTABLE_PartnerLogo/README.md b/packages/web/src/scss/components/UNSTABLE_PartnerLogo/README.md index edf01fc3dd..bf36963795 100644 --- a/packages/web/src/scss/components/UNSTABLE_PartnerLogo/README.md +++ b/packages/web/src/scss/components/UNSTABLE_PartnerLogo/README.md @@ -28,7 +28,7 @@ Use the `UNSTABLE_PartnerLogo--` modifier class to change the size of the
``` -## Disabled safe area +## Disabled Safe Area The PartnerLogo component can be displayed without the safe area (padding). Use `UNSTABLE_PartnerLogo--hasSafeAreaDisabled` modifier to disable safe area around logo. @@ -64,7 +64,7 @@ attribute is set on the container.
``` -## Full example +## Full Example ```html ``` -## Inverted variant +## Inverted Variant You can add an `UNSTABLE_ProductLogo--inverted` modifier class to invert the color of the background. It is necessary to insert the appropriate inverted logo variant as a children.