Skip to content

Commit

Permalink
Merge pull request #19 from askorama/feature/orm-1550-3
Browse files Browse the repository at this point in the history
Feature/ORM-1550-2
  • Loading branch information
rjborba authored Jul 30, 2024
2 parents 1c3480a + e044cd3 commit 23280d8
Show file tree
Hide file tree
Showing 49 changed files with 363 additions and 93 deletions.
2 changes: 1 addition & 1 deletion apps/demo-angular/package.json
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@
"build": "ng build",
"clean": "rm -rf node_modules .turbo dist",
"ng": "ng",
"start": "ng serve",
"dev": "ng serve",
"test": "ng test",
"watch": "ng build --watch --configuration development"
},
Expand Down
10 changes: 6 additions & 4 deletions apps/demo-angular/src/app/app.component.html
Original file line number Diff line number Diff line change
Expand Up @@ -5,10 +5,12 @@ <h1>App Angular</h1>

<section>
<h2>Stencil Components</h2>
<div class="component-row">
<!-- <my-button />
<my-button /><my-button /><my-button /><my-button /><my-button /><my-button /> -->
</div>
<orama-chat-box
[index]="{
api_key: 'yl2JSnjLNBV6FVfUWEyadpjFr6KzPiDR',
endpoint: 'https://cloud.orama.run/v1/indexes/recipes-m7w9mm',
}"
></orama-chat-box>
</section>
</main>

Expand Down
8 changes: 2 additions & 6 deletions apps/demo-angular/src/styles.css
Original file line number Diff line number Diff line change
@@ -1,3 +1,5 @@
@import '~@orama/angular-components/dist/component-library/styles.css';

/* You can add global styles to this file, and also import other style files */
#root {
background-color: #fff;
Expand Down Expand Up @@ -116,9 +118,3 @@ h2 {
section {
margin-bottom: 1rem;
}

.component-row {
background-color: #ddd;
padding: 1rem;
border-radius: 1rem;
}
5 changes: 4 additions & 1 deletion apps/demo-vue/src/App.vue
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,10 @@
<section>
<h2>Stencil Components</h2>
<div class="component-row">
<orama-chat-box />
<orama-chat-box :index="{
api_key: 'yl2JSnjLNBV6FVfUWEyadpjFr6KzPiDR',
endpoint: 'https://cloud.orama.run/v1/indexes/recipes-m7w9mm',
}" />
</div>
</section>
</main>
Expand Down
1 change: 0 additions & 1 deletion apps/demo-vue/src/main.ts
Original file line number Diff line number Diff line change
@@ -1,5 +1,4 @@
import { createApp } from 'vue'
import './style.css'
import { ComponentLibrary } from '@orama/vue-components'
import App from './App.vue'

Expand Down
2 changes: 1 addition & 1 deletion apps/storybook/components/basics/basics.jsx
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@ export const Basics = () => (
Named entities that store visual design properties. Used to ensure a scalable and consistent visual system for
UI development.
</p>
<a href="/">Design tokens</a>
<a href="/?path=/docs/design-tokens-introduction--docs">Design tokens</a>
</div>
<div className="box">
<h3 className="box__title">Components</h3>
Expand Down
77 changes: 77 additions & 0 deletions apps/storybook/stories/docs/DesignTokens.mdx
Original file line number Diff line number Diff line change
@@ -0,0 +1,77 @@
import { Meta } from '@storybook/blocks';

<Meta title="Design Tokens/Theming" />

# Theming with Design Tokens

Design tokens are a critical part of ensuring consistency and scalability in your design system. This guide shows how to avoid hardcoding values for colors, spacings, and typography by using tokens, while also supporting theme-specific styles using CSS custom properties.

## Global styles

We're using global styles that are available to all components and allow theme customization by exposing CSS custom properties.

We use the `mapToCustomProperties(map)` mixin to apply custom properties from a map of key-value pairs.
Theme switcher classes `.theme-light` and `.theme-dark` are used to apply the color tokens and they must be applied to the host element.
As an extra layer of safety, to avoid any possible collisions with same named custom properties defined in the hosting application under the same class name, we use the `id^='orama-ui'` selector to scope the custom properties, therefore all shadow hosts must have an id starting with `orama-ui`.


```css
[id^='orama-ui'] {
@include mapToCustomProperties($theme-light); // light theme is the default
@include mapToCustomProperties($theme-typography);
// other global styles...

&.theme-dark {
@include mapToCustomProperties($theme-dark);
}
}
```

## Colors
Instead of hardcoding color values, we use tokens defined in the global styles with support for themes. This approach allows you to easily switch between themes and maintain consistency across your application.

When applying styles in your components, use the CSS custom properties with a fallback to the Sass function, that provide a fallback value from a predefined palette:

```css
.my-component {
color: var(--text-color-primary, text-color(primary));
border: 1px solid var(--border-color-secondary, border-color(secondary));
background-color: var(--background-color-primary, background-color(primary));

}
```

## Spacings

Similar to colors, we define spacings using tokens:

```css
.my-component {
margin: var(--spacing-s, $spacing-s);
}
```

We don't use the Sass function to fallback for spacings, as we don't expect to change them based on color scheme. We use plain sass variables for spacings.

## Typography

Typography values should also use tokens for consistency across themes:

```css
.my-component {
font-size: var(--font-size-xs, $font-size-xs);
line-height: var(--font-line-height-s, $font-line-height-s);
}
```

## Radius

Border radius values should also use tokens for consistency across themes:

```css
.my-component {
border-radius: var(--radius-s, $radius-s);
}
```

By following these practices, you ensure that your styles are consistent, maintainable, and easy to update across your entire application while supporting theme-specific custom properties.
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,6 @@ Here you can find a collection of stories that showcase the Orama UI Kit compone
The Orama UI Kit is a collection of components and patterns that make up the design system. The components are designed to easily integrate search and chat functionality in your project. They are available as web components, React components, Vue components, and Angular components.

{/* create 3 boxes, one for Foundations, another for Components, and another for Contributing */}
<div class="boxes">
<div className="boxes">
<Basics />
</div>
49 changes: 49 additions & 0 deletions apps/storybook/stories/docs/frameworks/Angular.mdx
Original file line number Diff line number Diff line change
@@ -0,0 +1,49 @@
import { Meta } from '@storybook/blocks';

<Meta title="Usage/Frameworks/Angular" />

# Angular

We offer an Angular version of every public component so you can use them in your Angular projects.

## Installation

To add the Orama UI Kit to your Angulat project, run:

```bash
npm install @orama/angular-components
```
You can use pnpm or yarn if you prefer.

## Usage

In your `app.module.ts` file, import the component definition:

```tsx
import { ComponentLibraryModule } from '@orama/angular-components/dist/component-library'

@NgModule({
declarations: [AppComponent],
imports: [BrowserModule, AppRoutingModule, ComponentLibraryModule],
providers: [],
bootstrap: [AppComponent],
schemas: []
})
```

In order to apply the global styles to your Angular project, you need to import the styles in your Angular project's styles.css or styles.scss

```css
@import '~@orama/angular-components/dist/component-library/styles.css';
```

You can then use the components you need in your project:

```html
<orama-chat-box
[index]="{
api_key: 'your index api key',
endpoint: 'your index endpoint',
}"
></orama-chat-box>
```
41 changes: 41 additions & 0 deletions apps/storybook/stories/docs/frameworks/React.mdx
Original file line number Diff line number Diff line change
@@ -0,0 +1,41 @@
import { Meta } from '@storybook/blocks';

<Meta title="Usage/Frameworks/React" />

# React

We offer a React version of every public component so you can use them in your React projects.

## Installation

To add the Orama UI Kit to your React project, run:

```bash
npm install @orama/react-components
```
You can use pnpm or yarn if you prefer.

## Usage

In your `App.tsx` file, import the component definition and use it in your JSX:

```tsx
import { defineCustomElements } from '@orama/react-components'

void defineCustomElements()
```

You can then import and use the components you need in your project:

```tsx
import { OramaChatBox } from '@orama/react-components'

export const App = () => (
<OramaChatBox
index={{
api_key: 'your index api key',
endpoint: 'your index endpoint',
}}
/>
)
```
50 changes: 50 additions & 0 deletions apps/storybook/stories/docs/frameworks/Vue.mdx
Original file line number Diff line number Diff line change
@@ -0,0 +1,50 @@
import { Meta } from '@storybook/blocks';

<Meta title="Usage/Frameworks/Vue" />

# Vue

We offer an Angular version of every public component so you can use them in your Angular projects.

## Installation

To add the Orama UI Kit to your Angulat project, run:

```bash
npm install @orama/vue-components
```
You can use pnpm or yarn if you prefer.

## Usage

In your `app.module.ts` file, import the component definition:

```tsx
import { ComponentLibraryModule } from '@orama/angular-components/dist/component-library'

@NgModule({
declarations: [AppComponent],
imports: [BrowserModule, AppRoutingModule, ComponentLibraryModule],
providers: [],
bootstrap: [AppComponent],
schemas: []
})
```

We have to make sure that the global styles are referenced in the Angular project.
You can do this by importing the styles in your Angular project's styles.css or styles.scss

```css
@import '@orama/wc-components/dist/orama-ui/orama-ui.css';
```

You can then use the components you need in your project:

```html
<orama-chat-box
[index]="{
api_key: 'your index api key',
endpoint: 'your index endpoint',
}"
></orama-chat-box>
```
1 change: 1 addition & 0 deletions apps/storybook/stories/internal/orama-button.stories.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,7 @@ import { html } from 'lit-html'
const meta: Meta<Components.OramaButton> = {
title: 'Components/Internal/Button',
component: 'orama-button',
tags: ['autodocs'],
argTypes: {
variant: {
control: { type: 'select' },
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,7 @@ import type { Components } from '@orama/wc-components'
const meta: Meta<Components.OramaChatAssistentMessage> = {
title: 'Components/Internal/Chat',
component: 'orama-chat-assistent-message',
tags: ['autodocs'],
} satisfies Meta

export default meta
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,7 @@ import type { Components } from '@orama/wc-components'
const meta: Meta<Components.OramaChatMessagesContainer> = {
title: 'Components/Internal/Chat',
component: 'orama-chat-messages-container',
tags: ['autodocs'],
} satisfies Meta

export default meta
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,7 @@ import { fn } from '@storybook/test'
const meta: Meta<Components.OramaChatSuggestions> = {
title: 'Components/Internal/Chat',
component: 'orama-chat-suggestions',
tags: ['autodocs'],
}

export default meta
Expand Down
1 change: 1 addition & 0 deletions apps/storybook/stories/internal/orama-chat.stories.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,7 @@ import type { Components } from '@orama/wc-components'
const meta: Meta<Components.OramaChat> = {
title: 'Components/Internal/Chat',
component: 'orama-chat',
tags: ['autodocs'],
}

export default meta
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,7 @@ import type { Components } from '@orama/wc-components'
const meta: Meta<Components.OramaDotsLoader> = {
title: 'Components/Internal/DotsLoader',
component: 'orama-dots-loader',
tags: ['autodocs'],
}

export default meta
Expand Down
1 change: 1 addition & 0 deletions apps/storybook/stories/internal/orama-facets.stories.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,7 @@ import { fn } from '@storybook/test'
const meta: Meta<Components.OramaFacets> = {
title: 'Components/Internal/Facets',
component: 'orama-facets',
tags: ['autodocs'],
}

export default meta
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,7 @@ import type { Components } from '@orama/wc-components'
const meta: Meta<Components.OramaNavigationBar> = {
title: 'Components/Internal/NavigationBar',
component: 'orama-navigation-bar',
tags: ['autodocs'],
}

export default meta
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,7 @@ import type { Components } from '@orama/wc-components'
const meta: Meta<Components.OramaSearchResults> = {
title: 'Components/Internal/SearchResults',
component: 'orama-search-results',
tags: ['autodocs'],
}

export default meta
Expand Down
1 change: 1 addition & 0 deletions apps/storybook/stories/internal/orama-search.stories.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,7 @@ import type { Components } from '@orama/wc-components'
const meta: Meta<Components.OramaSearch> = {
title: 'Components/Internal/Search',
component: 'orama-search',
tags: ['autodocs'],
}

export default meta
Expand Down
1 change: 1 addition & 0 deletions apps/storybook/stories/internal/orama-toggler.stories.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,7 @@ import type { Components } from '@orama/wc-components'
const meta: Meta<Components.OramaToggler> = {
title: 'Components/Internal/Toggle',
component: 'orama-toggler',
tags: ['autodocs'],
} satisfies Meta

export default meta
Expand Down
Loading

0 comments on commit 23280d8

Please sign in to comment.