docs: Oryx components

_data/sidebars/scos_dev_sidebar.yml

@@ -3381,6 +3381,21 @@ entries:
             - title: Routing
               url: /docs/scos/dev/front-end-development/oryx/building-pages/oryx-routing.html
 
+        - title: Building Components
+              nested:
+                - title: Component Introduction
+                  url: /docs/scos/dev/front-end-development/{{page.version}}/oryx/building-components/component-introduction.html
+                - title: Component Types
+                  url: /docs/scos/dev/front-end-development/{{page.version}}/oryx/building-components/component-types.html
+                - title: Component Implementation
+                  url: /docs/scos/dev/front-end-development/{{page.version}}/oryx/building-components/component-implementation.html
+                - title: Component Definition
+                  url: /docs/scos/dev/front-end-development/{{page.version}}/oryx/building-components/component-definition.html
+                - title: Component Options
+                  url: /docs/scos/dev/front-end-development/{{page.version}}/oryx/building-components/component-options.html
+                - title: Component Interoperability
+                  url: /docs/scos/dev/front-end-development/{{page.version}}/oryx/building-components/components-interoperability.html
+
         - title: Architecture
           nested:
             - title: Dependency injection

docs/scos/dev/front-end-development/202212.0/oryx/building-components/component-definition.md

@@ -0,0 +1,46 @@
+---
+title: "Oryx Components Definition"
+description: Components are registered in an Oryx application by a definition file
+last_updated: Sept 19, 2023
+template: concept-topic-template
+---
+
+Oryx components can be integrated in different ways. Components can be listed in [pages](/docs/scos/dev/front-end-development/{{page.version}}/oryx/building-pages/oryx-pages.html) and [compositions](/docs/scos/dev/front-end-development/{{page.version}}/oryx/building-pages/oryx-compositions.html) or can be used inside other components or content integrated from a 3rd party CMS.
+
+When a component is rendered for the first time, Oryx resolves the component definition from the registry and loads the associated implementation. With this, components are lazily loaded.
+
+## Create a component definition
+
+To register a [component implementation](/docs/scos/dev/front-end-development/{{page.version}}/oryx/building-components/component-implementation.html), you need to provide a component definition. The component definition requires a name and implementation. The name is used as the (web) component element name. Web components require as least to be defined by 2 words, separated by a dash. It is a good practice to prefix your components by a vendor prefix, such as the project, brand or company name. This is why Oryx components are all prefixed with `oryx-`.
+
+{% info_block infoBox %}
+You can also update an existing component definition. To match an existing definition, you'd still need to provide a name.
+{% endinfo_block %}
+
+The example below shows an example where a new component is registered, providing both the name and implementation.
+
+```ts
+import { componentDef } from "@spryker-oryx/utilities";
+
+export const productIdComponent = componentDef({
+  name: "oryx-product-id",
+  impl: () => import("./id.component").then((m) => m.ProductIdComponent),
+});
+```
+
+The implementation is imported using the [static import declaration](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/import). This import binding is used by build systems such as [Vite](https://vitejs.dev/) to create a separate JavaScript chunk during the build. This allows to load the JavaScript chunk upon demand.
+
+## Register a component definition
+
+When you have created a component definition for your component, you need to configure it in the application. The [application orchestrator](/docs/scos/dev/front-end-development/{{page.version}}/oryx/building-applications/oryx-application-orchestration/oryx-application-orchestration.html) provides a `withComponents()` api that can be used to register an array of components.
+
+```ts
+import { appBuilder } from "@spryker-oryx/application";
+
+export const app = appBuilder().withComponents([
+  {
+    name: "oryx-product-id",
+    impl: () => import("./components/product/id.component"),
+  },
+]);
+```

docs/scos/dev/front-end-development/202212.0/oryx/building-components/component-implementation.md

@@ -0,0 +1,67 @@
+---
+title: "Oryx: Integrate Oryx Components in any web frameworks"
+description: Oryx Components are build as web components
+last_updated: Sept 12, 2023
+template: concept-topic-template
+---
+
+Oryx components are _framework agnostic_. This means that components can be used in other web frameworks.
+
+Oryx components are build as [web components](https://developer.mozilla.org/en-US/docs/Web/API/Web_components). Web components are a suite of standard web technologies, widely embraced by browser vendors. The purpose of web components is to provide components in isolation, so that they can easily integrate with other web technologies.
+
+Web components can be built by different frameworks or even with plain html, css and javascript. Oryx components are implemented with [Lit](https://lit.dev). Lit is a lightweight open source framework from Google that can be used to build highly efficient web components. If you do not want to use Lit, you can use your own framework of choice to create web components, see [component customization](/docs/scos/dev/front-end-development/{{page.version}}/oryx/building-components/component-customization.html).
+
+<!--
+Web components have a number of specific characteristics that have an impact on the implementation.
+- First and foremost, web components use a _shadow dom_. The main purpose of the shadow dom is to avoid leaking component styles to other components. While this is a great feature to have, it might be considered challenging when you like to intentionally manage styles at a central place in the application.
+- CSS custom properties (aka CSS variables) will pierce through the shadow DOM and are great to use inside design system components. Oryx uses CSS variables to manage styling through design tokens.
+- Not all native events bubble up outside the shadow DOM. Events must be flagged with the _composed_ property to bubble outside the shadow DOM.
+- Component styles use the `:host` selector as a root level selector for the component.  -->
+
+## Integrate in other web frameworks
+
+Thanks to the web component based architecture, Oryx components integrate with any web framework. You can integrate Oryx components inside component frameworks, such as [React](https://react.dev/), [Vue.js](https://vuejs.org/), [Angular](https://angular.io/).
+
+You can also integrate Oryx components inside frontend meta frameworks, like [Next.js](https://nextjs.org/), [Nuxt.js](https://nuxt.com/), or [Astro](https://astro.build/).
+
+{% info_block infoBox %}
+While the integration of Oryx components is relative straightforward, Spryker does not provide production ready integration boilerplate code.
+
+The integration of the [server side rendering (SSR)](/docs/scos/dev/front-end-development/oryx/oryx-server-side-rendering.html) part might be more complex than you'd expect.
+{% endinfo_block %}
+
+## Integrate in Content Management Systems
+
+Oryx can render content from other systems such as headless Content Management Systems (CMS). This is pretty standard approach. A more exciting feature of Oryx is that Oryx components can render inside the content, provided by a CMS.
+
+Whenever rich content, such as markdown, contains Oryx components, the components can render as-is when the content is rendered in Oryx. This allows for rich integrations deeply in the content, for example by rendering a carousel of upsell products in the middle of some storytelling content.
+
+You can use oryx components inside rich content coming from an external CMS. The content will be rendered inside Oryx, but any Oryx components listed inside the content will be rendered transparently. This does not need any integration effort.
+
+The following example shows a markdown file that contains standard markdown plus some Oryx components.
+
+```markdown
+## Markdown example with an integrate Oryx Product images
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit...
+
+<oryx-product-images sku="086_30521602"></oryx-product-images>
+
+Duis aute irure dolor in reprehenderit in voluptate velit...
+```
+
+Another nice example show the integration of compositions with layout. In the following example we use the product list component with a configuration to render it in a carousel.
+
+```markdown
+## Markdown example with a carousel of products
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit...
+
+<oryx-product-list layout="carousel"></oryx-product-product-list>
+
+Duis aute irure dolor in reprehenderit in voluptate velit...
+```
+
+## Integrate in Spryker Yves
+
+The integration of Oryx components inside Yves is very appealing, especially for customers who want ot gradually migrate their implementation from Yves to Oryx. While the client side rendering of web components is straightforward, the server side rendering requires a node-like application that renders the components. Yves does not provide such infrastructure as a standard feature, but a POC has been conducted to ensure the technical feasibility between Yves and Oryx.

docs/scos/dev/front-end-development/202212.0/oryx/building-components/component-introduction.md

@@ -0,0 +1,32 @@
+---
+title: "Oryx: Building Components"
+description: Components are the building blocks of Oryx Applications
+last_updated: Sept 10, 2023
+template: concept-topic-template
+---
+
+Oryx provides a fully component-based architecture, where only components are used to render the application. Components are the building blocks that developers can use to create modular and reusable elements. The components are primarily concerned with the UI/UX, leaving business logic and integrations to other application layers.
+
+Oryx contains a library of standard components, organized and distributed in [packages](/docs//scos/dev/front-end-development/{{page.version}}/getting-started/oryx-packages.html). There are different [types of components](/docs/scos/dev/front-end-development/{{page.version}}/oryx/building-components/component-types.html), including a design system. The components are build with strong usability features, including:
+
+- Responsive design
+- Themable (using [design tokens](/docs/scos/dev/front-end-development/{{page.version}}/oryx/building-applications/styling/oryx-design-tokens.html))
+- [Typography](/docs/scos/dev/front-end-development/{{page.version}}/oryx/building-applications/styling/oryx-typography.html)
+- [Icon system](/docs/scos/dev/front-end-development/{{page.version}}/oryx/building-applications/styling/oryx-icon-system.html)
+- Internationalization (i18n) features:
+  - [locales](/docs/scos/dev/front-end-development/{{page.version}}/oryx/architecture/dependency-injection/oryx-service-layer.html)
+  - number and price formatting
+  - directionality (left-to-right vs right-to-left)
+- Accessibility features:
+  - dark and light mode
+  - [color contrast](/docs/scos/dev/front-end-development/{{page.version}}/oryx/building-applications/styling/oryx-color-system.html)
+  - keyboarding
+  - screen reader support
+
+Oryx components are rendered inside [compositions](/docs/scos/dev/front-end-development/{{page.version}}/oryx/building-pages/oryx-compositions.html) and [pages](/docs/scos/dev/front-end-development/{{page.version}}/oryx/building-pages/oryx-pages.html). The pages and the organization and layout of the components are provided in standard [feature sets](/docs/scos/dev/front-end-development/{{page.version}}/oryx/oryx-feature-sets.html). When you install an Oryx application, the feature sets are installed from the [presets](/docs/scos/dev/front-end-development/{{page.version}}/oryx/building-applications/oryx-presets.html) package.
+
+You can use standard components in your application in combination with custom components. A common approach is to start your project with the standard components and configure the application theme and [component options](/docs/scos/dev/front-end-development/{{page.version}}/oryx/building-components/component-options.html) to meet the application design. When the application requires a custom component, you can [implement your custom components](/docs/scos/dev/front-end-development/{{page.version}}/oryx/building-components/components-implementation.html) or customize an existing Oryx components.
+
+Oryx components are built as web components, which makes them highly reusable in other web frameworks and systems. Read more about the [interoperability of Oryx components](/docs/scos/dev/front-end-development/{{page.version}}/oryx/building-components/components-interoperability.html) in other frameworks and systems.
+
+Oryx provides a reactive framework and is designed to work highly efficiently in a Single Page Application architecture. To ensure _reactivity_ throughout the application, Oryx only re-renders those fragments of the components that have been affected by the changing application state. You can read more about this in the [key concepts of reactivity](/docs/scos/dev/front-end-development/{{page.version}}/oryx/architecture/reactivity/key-concepts-of-reactivity.html).

docs/scos/dev/front-end-development/202212.0/oryx/building-components/component-options.md

@@ -0,0 +1,126 @@
+---
+title: "Oryx Components Options"
+description: Components Options provide reusable components cross business models
+last_updated: Sept 19, 2023
+template: concept-topic-template
+---
+
+## Component options
+
+Oryx components can be provided with options. Component options are javascript objects that can be configured as part of the application configuration, to make the components better reusable in different business contexts.
+
+We use the display of a tax message ("incl. vat") in the `ProductPriceComponent` as an example for this documentation. Rendering the tax message might be subject to the business context (think b2b vs b2c) or driven by the legal context. In order to reuse the component in different context, the tax message condition can be given by an option. Such option can be specified on the application.
+
+## Define component options
+
+It is recommended to define component options in TypeScript. This ensures a good developer experience for both the component implementation as well as the application configuration.
+
+Oryx provides a mixin `ContentMixin` to work with component options. You can use the mixin to hand in the option interface. The code below shows the usage of the mixin for the definition of the options.
+
+```ts
+export interface ProductPriceOptions {
+  /**
+   * Indicates whether to show tax message for the price.
+   */
+  enableTaxMessage?: boolean;
+}
+
+export class ProductPriceComponent extends ContentMixin<ProductPriceOptions>(
+  LitElement
+) {
+  // ...
+}
+```
+
+## Default values
+
+Components can set up default values for the component options. The default values are used as fallback in case there are no specific values provided.
+
+Oryx provides a class decorator (`@defaultOptions`) that can be used to add the default values.
+
+```ts
+@defaultOptions({
+  enableTaxMessage: true,
+})
+export class ProductPriceComponent extends ContentMixin<ProductPriceOptions>(
+  LitElement
+) {
+  // ...
+}
+```
+
+### Load component options
+
+Component options can be provided statically to the application and will be used by all instances of the component.
+
+```ts
+export const app = appBuilder()
+  .withOptions({
+    "oryx-product-price": {
+      enableTaxMessage: false,
+    },
+  })
+  .create();
+```
+
+You can read more about setting up the application in the [application-orchestration documentation](https://docs.spryker.com/docs/scos/dev/front-end-development/202307.0/oryx/oryx-application-orchestration/oryx-application-orchestration.html).
+
+Another approach to provide static options, is providing them in the experience data. When you configure the values through experience data, you can configure values for a particular instance of the component.
+
+In the following configuration example you see a part of the experience data that sets the `enableSalesLabel` option to false. This override the `enableSalesLabel` for this particular usage. When the component is used in other instances (say inside a product card), this configuration will not have any effect.
+
+```ts
+...
+{
+    type: 'oryx-composition',
+    components: [
+        ...
+        {
+            type: 'oryx-product-price',
+            options: { enableSalesLabel: false },
+        },
+        ...
+    ]
+}
+```
+
+You can read more about creatign and customizing experience data in the
+[page documentation](/docs/scos/dev/front-end-development/202307.0/oryx/building-pages/oryx-pages.html).
+
+Component options values can also be loaded dynamically from a backend API. Loading options from APIs will allow you to factor in additional context to create component options. For example, you could create personalization or A/B testing scenario's in the component option values.
+
+### Use component options
+
+To use component options in an asynchronous fashion, it is important to observe the options and react to updates in the component UI. Oryx provides a reactive framework with observable data streams that can update the UI using signals. To simplify the integration in component logic, the `ContentMixin` provides an `$options` signal, that be called in the render logic or other signals.
+
+The following code shows how to use the `$options` signal. Due to the component option interface the usage of the signal is type safe.
+
+```ts
+
+```
+
+In order to load options statically
+
+This option
+a signal, that ensures that the content is
+
+see [Signals](/docs/scos/dev/front-end-development/{{page.version}}/oryx/reactivity/signals.html).
+
+```ts
+@defaultOptions({
+  enableTaxMessage: true,
+})
+export class ProductPriceComponent extends ContentMixin<ProductPriceOptions>(
+  LitElement
+) {
+  protected override render(): TemplateResult {
+    return html` ... ${this.renderTaxMessage()} ... `;
+  }
+
+  protected renderTaxMessage(): TemplateResult | void {
+    if (!this.$options().enableTaxMessage) return;
+
+    return html`...`;
+  }
+}
+```