Somfy UI

Somfy UI est une librairie de Web Components construite avec Stencil pour etre consommee par des applications framework-agnostiques, notamment Vue.

Tous les composants exposes utilisent le prefixe smf-.

Installation

npm install somfy-ui

Usage

Le mode d'integration recommande consiste a enregistrer les custom elements via le loader, puis a importer les styles globaux necessaires.

import { defineCustomElements } from 'somfy-ui/loader';
import 'somfy-ui/styles/fonts.css';
import 'somfy-ui/styles/sizes.css';
import 'somfy-ui/styles/eases.css';
import 'somfy-ui/styles/theme-light.css';

defineCustomElements();

Ensuite les composants peuvent etre utilises directement dans le markup :

<smf-button label="Valider"></smf-button>
<smf-input-text label="Nom" placeholder="Votre nom"></smf-input-text>

Integration Vue

Dans une application Vue, l'enregistrement des custom elements se fait une seule fois au demarrage de l'application :

import { createApp } from 'vue';
import App from './App.vue';
import { defineCustomElements } from 'somfy-ui/loader';
import 'somfy-ui/styles/fonts.css';
import 'somfy-ui/styles/sizes.css';
import 'somfy-ui/styles/eases.css';
import 'somfy-ui/styles/theme-light.css';

defineCustomElements();

createApp(App).mount('#app');

Declarer les custom elements

Par defaut, Vue tente de resoudre les tags non natifs comme des composants Vue. Pour eviter les warnings, il faut indiquer a Vue de traiter les tags prefixes smf- comme des custom elements.

Vite (vite.config.ts) :

import vue from '@vitejs/plugin-vue';

export default {
    plugins: [
        vue({
            template: {
                compilerOptions: {
                    isCustomElement: tag => tag.startsWith('smf-'),
                },
            },
        }),
    ],
};

Vue CLI (vue.config.js) :

module.exports = {
    chainWebpack: config => {
        config.module
            .rule('vue')
            .use('vue-loader')
            .tap(options => {
                options.compilerOptions = {
                    ...options.compilerOptions,
                    isCustomElement: tag => tag.startsWith('smf-'),
                };
                return options;
            });
    },
};

Exemple de composant Vue :

<template>
    <smf-input-text
        label="Email"
        :value="email"
        @smfInput="onInput"
    />
</template>

<script setup lang="ts">
import { ref } from 'vue';

const email = ref('');

function onInput(event: CustomEvent<string>) {
    email.value = event.detail;
}
</script>

Integration React

React 19+ supporte nativement les custom elements. Pour les versions anterieures, les props et events doivent etre passes via des refs.

React 19+

Les props et events fonctionnent directement :

function App() {
    const [email, setEmail] = useState('');

    return (
        <smf-input-text
            label="Email"
            value={email}
            onSmfInput={(e: CustomEvent<string>) => setEmail(e.detail)}
        />
    );
}

React 18 et anterieur

React ne transmet pas les props aux custom elements comme attributs. Utiliser une ref pour setter les proprietes et ecouter les events :

import { useRef, useEffect, useState } from 'react';

function App() {
    const inputRef = useRef<HTMLElement>(null);
    const [email, setEmail] = useState('');

    useEffect(() => {
        const el = inputRef.current;
        if (!el) return;

        const handler = (e: Event) => setEmail((e as CustomEvent<string>).detail);
        el.addEventListener('smfInput', handler);
        return () => el.removeEventListener('smfInput', handler);
    }, []);

    useEffect(() => {
        if (inputRef.current) {
            (inputRef.current as any).value = email;
        }
    }, [email]);

    return <smf-input-text ref={inputRef} label="Email" />;
}

Typage JSX

Pour eviter les erreurs TypeScript sur les tags smf-*, ajouter une declaration de types (par exemple src/custom-elements.d.ts) :

import type { JSX as SmfJSX } from 'somfy-ui';

declare module 'react' {
    namespace JSX {
        interface IntrinsicElements {
            'smf-button': SmfJSX.SmfButton & React.HTMLAttributes<HTMLElement>;
            'smf-input-text': SmfJSX.SmfInputText & React.HTMLAttributes<HTMLElement>;
            // ajouter les autres composants utilises
        }
    }
}

Integration Angular

Enregistrement

Dans le fichier main.ts, appeler le loader avant le bootstrap :

import { defineCustomElements } from 'somfy-ui/loader';
import 'somfy-ui/styles/fonts.css';
import 'somfy-ui/styles/sizes.css';
import 'somfy-ui/styles/eases.css';
import 'somfy-ui/styles/theme-light.css';

defineCustomElements();

platformBrowserDynamic().bootstrapModule(AppModule);

Declarer les custom elements

Ajouter CUSTOM_ELEMENTS_SCHEMA au module (ou au composant standalone) pour qu'Angular accepte les tags smf-* :

Module classique :

import { NgModule, CUSTOM_ELEMENTS_SCHEMA } from '@angular/core';

@NgModule({
    declarations: [AppComponent],
    schemas: [CUSTOM_ELEMENTS_SCHEMA],
    bootstrap: [AppComponent],
})
export class AppModule {}

Composant standalone :

import { Component, CUSTOM_ELEMENTS_SCHEMA } from '@angular/core';

@Component({
    selector: 'app-root',
    standalone: true,
    schemas: [CUSTOM_ELEMENTS_SCHEMA],
    template: `<smf-button label="Valider"></smf-button>`,
})
export class AppComponent {}

Exemple

<smf-input-text
    label="Email"
    [value]="email"
    (smfInput)="onInput($event)"
></smf-input-text>

export class AppComponent {
    email = '';

    onInput(event: CustomEvent<string>) {
        this.email = event.detail;
    }
}

Integration JavaScript vanilla

Aucune configuration framework n'est necessaire. Importer le loader et les styles, puis utiliser les composants directement dans le HTML.

Via bundler (Vite, Webpack, etc.)

import { defineCustomElements } from 'somfy-ui/loader';
import 'somfy-ui/styles/fonts.css';
import 'somfy-ui/styles/sizes.css';
import 'somfy-ui/styles/eases.css';
import 'somfy-ui/styles/theme-light.css';

defineCustomElements();

Via CDN (sans bundler)

<!DOCTYPE html>
<html lang="fr">
<head>
    <link rel="stylesheet" href="https://unpkg.com/somfy-ui/styles/fonts.css" />
    <link rel="stylesheet" href="https://unpkg.com/somfy-ui/styles/sizes.css" />
    <link rel="stylesheet" href="https://unpkg.com/somfy-ui/styles/eases.css" />
    <link rel="stylesheet" href="https://unpkg.com/somfy-ui/styles/theme-light.css" />
    <script type="module" src="https://unpkg.com/somfy-ui/dist/somfy-ui/somfy-ui.esm.js"></script>
</head>
<body>
    <smf-button label="Valider"></smf-button>
</body>
</html>

Interaction avec les composants

const input = document.querySelector('smf-input-text');

// Setter une propriete
input.value = '[email protected]';

// Ecouter un event custom
input.addEventListener('smfInput', event => {
    console.log('Nouvelle valeur :', event.detail);
});

Exports publics supportes

Les points d'entree publics du package sont :

• somfy-ui
• somfy-ui/loader
• somfy-ui/styles/fonts.css
• somfy-ui/styles/sizes.css
• somfy-ui/styles/eases.css
• somfy-ui/styles/theme-light.css
• somfy-ui/icons/*

Les applications consommatrices ne doivent pas importer de chemins internes hors de ces exports.

Composants

Le package expose actuellement les composants suivants :

• smf-button
• smf-button-icon
• smf-card
• smf-checkbox
• smf-drag-item
• smf-drag-list
• smf-icon
• smf-input-area
• smf-input-file
• smf-input-search
• smf-input-text
• smf-loader
• smf-modal
• smf-navigation-item
• smf-radio
• smf-radio-group
• smf-select
• smf-select-option
• smf-switch-control
• smf-switch-item
• smf-tab
• smf-tab-panel
• smf-table
• smf-table-body
• smf-table-cell
• smf-table-footer
• smf-table-head
• smf-table-header
• smf-table-row
• smf-tabs
• smf-tag
• smf-toast

Developpement

npm start
npm run build
npm test
npm run storybook