DEV Community: Jives

Gathering Hyrox Race Insights with Python

Jives — Thu, 19 Mar 2026 20:40:30 +0000

Overview

I've been training for a while now for a series of Hyrox races. I did a mixed doubles race over the holidays, my first solo race last month, and I'm currently working up for another solo in the mid-year. While I've been doing the usual training and preparation, I wanted to take a deeper look at my performance compared to others to see if I can find any insights to improve my time in my next race. If this is something you've been interested in doing, then hopefully this post can provide some insights into how you can do the same with a little bit of Python.

Fetching the Race Results

Before we can begin to analyse anything, we need to get the data. Hyrox has a public leaderboard where you can view race results, but it doesn’t offer any way to export the data other than printing the page. Fortunately, there’s an unofficial Python API available called the pyrox-client that we can use to export the data in a more usable format. Use the following boilerplate, configure the parameters to get the data for your desired race, and run the script.

import os
import pyrox
import pandas as pd
from rich.console import Console
from rich.table import Table

class HyroxRaceInsights:
    """Analyses Hyrox race data and generates performance insights."""

    ALL_EVENTS: dict[str, str] = {
        "run1_time": "Run 1",
        "skiErg_time": "SkiErg",
        # ... remaining events
    }

    def fetch_data(self) -> None:
        """Fetch race data from Pyrox API."""
        client = pyrox.PyroxClient()
        race = client.get_race(
            season=self.season,
            location=self.location,
            gender=self.gender,
            division=self.division,
        )
        self.race_records = race.to_dict(orient="records")
        self._find_athlete()
        self._calculate_averages()

# Load configuration from environment variables
season = int(os.environ.get("HYROX_SEASON", "8"))
division = os.environ.get("HYROX_DIVISION", "open")
gender = os.environ.get("HYROX_GENDER", "male")
location = os.environ.get("HYROX_LOCATION", "Stockholm")
athlete = os.environ.get("HYROX_ATHLETE", "Smith, John")

analyzer = HyroxRaceInsights(season=season, location=location, division=division, gender=gender, athlete_name=athlete)
analyzer.fetch_data()

Now that we have the data, we can begin to visualise it, let's get started! I want to see where I fall within the average for each event and also where my biggest opportunities are. First, I wrote some code to calculate the event averages.

    def _calculate_averages(self) -> None:
        """Calculate field average times for each event."""

        self.averages = {
            field: sum(times) / len(times)
            for field in self.ALL_EVENTS
            if (times := [r[field] for r in self.race_records if r.get(field) is not None])
        }

I needed to find my own record in the data set for comparison. I broke this into a utility method called _find_athlete which locates it by name:

    def _find_athlete(self) -> None:
        """Locate athlete record in race data."""

        for record in self.race_records:
            if str(record.get("name", "")).lower() == self.athlete_name.lower():
                self.athlete_record = record
                break

I could then identify where I fell within those averages by comparing my time at each station against the field average. I arranged it into a table that makes it easy to understand using the Rich library.

    def _display_athlete_comparison_table(self) -> None:
        """Show athlete times vs field averages."""

        table = Table(title=f"Athlete Comparison - {self.athlete_name}")
        table.add_column("Event", style="cyan")
        table.add_column("Your Time", style="yellow")
        table.add_column("Field Avg", style="magenta")
        table.add_column("Delta", style="white")

        for field, event_name in self.ALL_EVENTS.items():
            athlete_time = self.athlete_record.get(field)
            avg_time = self.averages.get(field)
            if athlete_time and avg_time:
                delta = athlete_time - avg_time
                color = self._delta_color(delta)
                table.add_row(
                    event_name,
                    f"{athlete_time:.2f}m",
                    f"{avg_time:.2f}m",
                    f"[{color}]{delta:+.2f}m[/{color}]",
                )

To get the biggest opportunities, I calculated how far I had strayed from the average in the other direction. In the rare case that anything is ever well above the average, it is calculated relative to whatever is closest to the average (I'll get there one day).

    def _display_opportunities(self) -> None:
        """Show top 3 events where athlete lost the most time."""

        # Filter events where we lost time and sort by biggest loss first
        opportunities = sorted(
            [(n, d, p) for n, d, p in self.heatmap_data if d > 0],
            key=lambda x: x[1],
            reverse=True,
        )

        if opportunities:
            max_delta = opportunities[0][1]
            for i, (event_name, delta_sec, delta_pct) in enumerate(
                opportunities[: self.TOP_N_OPPORTUNITIES], 1
            ):
                bar = self._make_bar((delta_sec / max_delta) * 25)
                self.console.print(
                    f"  {i}. {event_name:20} [red]{bar}[/red] "
                    f"[red bold]+{delta_sec:.0f}s[/red bold]"
                )

I also wanted to see a heatmap that shows where I gained or lost time relative to the field average so I know where to focus my training.

    def _display_heatmap(self) -> None:
        """Show per-event delta vs field average."""

        self.heatmap_data = self._compute_event_deltas()

        # Print each event sorted by delta, with a colored symbol and bar
        for event_name, delta_sec, delta_pct in sorted(self.heatmap_data, key=lambda x: x[1]):
            color = self._delta_color(delta_sec)
            symbol = "✓" if delta_sec < 0 else "✗"
            bar = self._make_bar(abs(delta_sec) / 10)

            self.console.print(
                f"  {event_name:20} [{color}]{symbol}[/{color}] "
                f"{bar} {delta_sec:+6.0f}s"
            )

As a result I get some pretty charts that show me where I'm doing well and where I need to focus my efforts.

If you wanted to take this one step further, you could instead export the data and build an entire app around it using something like ApexCharts or D3 to create more interactive visualisations. You could even build a dashboard that tracks your performance over time across multiple races. Lots of interesting possibilities here as the data set is pretty rich. I highly recommend checking out the pyrox-client documentation to see what other data you can pull from the API to enrich your analysis.

Heart Rate Analysis

If you recorded your heart rate during your Hyrox race, you can use that to further enrich the data set to see where your heart rate spiked and how it correlates with your performance. This can be especially useful for endurance events like Hyrox, where pacing is important. I updated my script to read a heart_rate.csv file I generated from my Apple Watch export and built some additional visualisations to show how my heart rate changed throughout the event.

    def _load_heart_rate_data(self) -> None:
        """Load heart rate data from CSV if it exists."""

        heart_rate_file = "heart_rate.csv"
        if not os.path.exists(heart_rate_file):
            return

        try:
            df = pd.read_csv(heart_rate_file)
            # Validate required columns
            if not all(col in df.columns for col in self.HR_REQUIRED_COLUMNS):
                return
            self.heart_rate_data = df
        except (pd.errors.ParserError, OSError) as e:
            self.console.print(
                f"[yellow]Warning:[/yellow] Could not load heart rate data: {e}"
            )

I know I always start my watch when the race begins, so I wrote code to trim the end of the reading, as 9 times out of 10 I forget to turn it off right away when I cross the finish line. The following method maps heart rate readings to each station using cumulative time, and cuts off any data beyond the total race duration.

    def _display_heart_rate_per_station(self) -> None:
        """Show average heart rate per event."""

        event_hr_data = self._hr_per_event(self._hr_avg_values, self._hr_max_values)
        max_avg_hr = max(hr for _, hr, _ in event_hr_data)

        for event_name, avg_hr, max_hr in sorted(
            event_hr_data, key=lambda x: x[1], reverse=True
        ):
            bar = self._make_bar((avg_hr / max_avg_hr) * 30)
            self.console.print(
                f"  {event_name:20} {bar} [yellow]{avg_hr:.0f}[/yellow] bpm"
            )

With data mapped per station, I could then identify the peak exertion moments where my heart rate spiked the most. In other words, where I suffered.

    def _display_heart_rate_spikes(self) -> None:
        """Show where heart rate spiked the most."""
        spike_data = self._hr_per_event(self._hr_avg_values, self._hr_max_values)
        top_spikes = sorted(spike_data, key=lambda x: x[2], reverse=True)[:3]
        max_peak_hr = max(hr for _, hr, _ in spike_data)

        for i, (event_name, _, peak_hr) in enumerate(top_spikes, 1):
            bar = self._make_bar((peak_hr / max_peak_hr) * 30)
            self.console.print(
                f"  {i}. {event_name:20} [red]{bar}[/red] Peak: {peak_hr:.0f} bpm"
            )

As a result you get some additive insights that can help you figure out where you might be pushing a bit too hard, or opportunities where you can push even harder.

Conclusion

If you'd like to give my script a try you can find it on GitHub. Big thanks to the maintainers of the pyrox-client library for making it easy to access the data used here.

Hopefully, this article gives you some ideas for analysing your own performance. The key is to find a way to visualise the data that makes it easy to understand and draw insights from. Whether it’s a simple bar chart or a more complex visualisation, the important thing is to use the data to inform your training and help you improve. Good luck with your next race!

Headless Storybook with Lit

Jives — Thu, 19 Mar 2026 20:28:06 +0000

Storybook offers key advantages for component development, especially when building a design system. It addresses common challenges out of the box and streamlines your workflow. However, the abstraction that Storybook offers can obscure critical insights into component behaviour in real-world deployment scenarios, particularly with server-side rendering (SSR).

Server-side rendering is the process of generating HTML markup on the server before transmitting it to the client. This approach reduces the client-side computational load on the browser during page rendering, thereby enhancing performance, search engine optimisation (SEO), and related metrics. However, server-side rendering introduces added complexity, particularly when integrating with Web Components, making setup and ongoing maintenance more challenging.

Let's take Lit, a Web Component framework that my team uses as an example. An experimental server-side rendering feature exists that relies on the declarative shadow DOM, but for correct hydration, components must be adhere to certain lifecycle constraints. For instance, if certain rendering logic is placed in improper lifecycle callbacks, a component may render as expected in Storybook but fail during server-side rendering. This results in significant time spent debugging discrepancies between development and production. Tooling for static analysis, such as linting and lifecycle enforcement, is relatively immature due to the feature's experimental status, and replicating server-side rendering-specific conditions in Storybook is currently not feasible.

As my team relies heavily on Storybook for development and documentation, I wanted to find a low-cost way to provide visibility into how our components render with Next.js. Our bandwidth is limited, so I didn't want to set up a number of manually curated examples as we're already doing that in Storybook. Instead, I wanted to find a way to mirror exactly what we have in Storybook in Next.js so we can easily identify any discrepancies and fix them before they reach production.

Leveraging CSF

One of my favourite changes to Storybook in recent memory was the switch towards the Component Story Format (CSF). This format standardises how "stories" are written across similar applications to Storybook. If you're unfamiliar with the term "story", they represent a single rendering of a component; for example, a button's primary colour could be a story, and its secondary colour could be another; they are, in essence, common configurations, things your design system users would be looking for when they browse your catalogue of components.

As we're already writing CSF, what if we could combine those objects with the Custom Elements Manifest (CEM) to create an exportable representation of a story that can be rendered more directly within Next.js? The Custom Elements Manifest lists every component and its properties in our component library already. It should be relatively straightforward to use it to connect the dots between the CSF object and its associated component, thereby reconstructing the markdown that Storybook uses in its rendering. Here's the plan:

Parse through the Custom Elements Manifest using a custom plugin for @open-wc/analyzer.
Use the source path to find the component's associated story file. This works if you follow the common convention of colocating your stories with your components.
Import the exported CSF object and resolve any variables, merge the data with the component metadata from the Custom Elements Manifest.
Render the component in Next.js using the tag name, attributes and slot content from the enriched manifest.

Walking the AST

Let's start by writing the plugin. We’ll hook into the packageLinkPhase, which executes after the manifest has been fully assembled and provides access to the complete component metadata. Once activated, the plugin locates all .stories.ts files, parses each one, and merges the story args with the CEM’s attribute defaults and slot definitions.
The following code samples have been simplified for readability.

export default function cemStoryArgsPlugin(options = {}) {
  const {
    srcDir = 'src',
    outDir = 'dist',
    fileName = 'stories-manifest.json',
  } = options;

  return {
    name: 'cem-story-args',
    packageLinkPhase({customElementsManifest}) {
      const srcPath = path.join(process.cwd(), srcDir);
      const storyFiles = findStoryFiles(srcPath);

      const storiesManifest = {
        version: '1.0.0',
        generatedAt: new Date().toISOString(),
        totalComponents: 0,
        totalStories: 0,
        components: {},
      };

      for (const storyFile of storyFiles) {
        const extracted = parseStoryFile(storyFile, srcPath);

        if (extracted.component && extracted.stories.length > 0) {

          // Find matching CEM component data
          const cemComponent = customElementsManifest?.modules
            ?.flatMap(m => m.declarations || [])
            ?.find(d => d.tagName === extracted.component);

          // Build default args from CEM attributes and slots
          const defaultArgs = {};
          const defaultSlots = {};

          cemComponent?.attributes?.forEach(attr => {
            if (attr.default !== undefined) {
              defaultArgs[attr.name] = parseDefault(attr.default);
            }
          });

          cemComponent?.slots?.forEach(slot => {
            defaultSlots[slot.name] = '';
          });

          // Merge CEM defaults with story-specific overrides
          const storiesWithDefaults = extracted.stories.map(story => ({
            ...story,
            args: {...defaultArgs, ...story.args},
            slots: {...defaultSlots, ...story.slots},
          }));

          storiesManifest.components[extracted.component] = {
            tagName: extracted.component,
            storyFile: extracted.file,
            schema: {},
            stories: storiesWithDefaults,
          };
        }
      }

      const outputPath = path.resolve(process.cwd(), outDir, fileName);
      writeFileIfChanged(outputPath, JSON.stringify(storiesManifest, null, 2));
    },
  };
}

The core of the plugin is parseStoryFile, which uses TypeScript’s AST (Abstract Syntax Tree) to walk through each story file. It collects variable declarations first so it can resolve references, then looks for the meta export and each named story export:

function parseStoryFile(filePath, srcDir) {
  const content = fs.readFileSync(filePath, 'utf-8');
  const sourceFile = ts.createSourceFile(
    filePath, content, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS,
  );

  const result = {
    file: path.relative(srcDir, filePath),
    component: null,
    stories: [],
  };

  const variableDeclarations = new Map();

  // Resolve imports from other files first
  resolveImports(sourceFile, filePath, variableDeclarations);

  // Collect local variable declarations
  ts.forEachChild(sourceFile, node => {
    if (ts.isVariableStatement(node)) {
      node.declarationList.declarations.forEach(decl => {
        if (ts.isIdentifier(decl.name) && decl.initializer) {
          const value = evaluateNode(
            decl.initializer, sourceFile, variableDeclarations,
          );
          variableDeclarations.set(decl.name.text, value);
        }
      });
    }
  });

  // Find exported story constants
  ts.forEachChild(sourceFile, node => {
    if (
      ts.isVariableStatement(node) &&
      node.modifiers?.some(m => m.kind === ts.SyntaxKind.ExportKeyword)
    ) {
      node.declarationList.declarations.forEach(decl => {
        if (
          ts.isIdentifier(decl.name) &&
          decl.initializer &&
          ts.isObjectLiteralExpression(decl.initializer)
        ) {
          const story = { name: decl.name.text, args: {}, slots: {} };

          decl.initializer.properties.forEach(prop => {
            if (ts.isPropertyAssignment(prop)) {
              const propName = getPropertyName(prop.name, sourceFile);

              if (propName === 'args' &&
                  ts.isObjectLiteralExpression(prop.initializer)) {
                prop.initializer.properties.forEach(argProp => {
                  if (ts.isPropertyAssignment(argProp)) {
                    const key = getPropertyName(argProp.name, sourceFile);
                    const value = evaluateNode(
                      argProp.initializer, sourceFile, variableDeclarations,
                    );

                    // Slot args are suffixed with '-slot' by convention
                    if (key?.endsWith('-slot')) {
                      story.slots[key.replace('-slot', '')] = value;
                    } else if (key) {
                      story.args[key] = value;
                    }
                  }
                });
              }
            }
          });

          result.stories.push(story);
        }
      });
    }
  });

  return result;
}

The reason we need the AST instead of simply importing the story files is that they often contain Storybook-specific constructs, decorators and framework imports that aren’t resolvable outside of a Storybook context. By walking the AST, we can extract only the data we need (the arg objects) without executing the code.

The evaluateNode function converts AST nodes into plain JavaScript values. It recurses through objects, arrays, and literals, and can even resolve variable references that were collected earlier:

function evaluateNode(node, sourceFile, variableDeclarations) {
  if (!node) return undefined;

  switch (node.kind) {
    case ts.SyntaxKind.StringLiteral:
      return node.text;
    case ts.SyntaxKind.NumericLiteral:
      return Number(node.text);
    case ts.SyntaxKind.TrueKeyword:
      return true;
    case ts.SyntaxKind.FalseKeyword:
      return false;
    case ts.SyntaxKind.Identifier: {
      // Resolve variable references
      const varName = node.text;
      if (variableDeclarations.has(varName)) {
        return variableDeclarations.get(varName);
      }
      return `{{${varName}}}`;
    }
    case ts.SyntaxKind.ObjectLiteralExpression: {
      const obj = {};
      node.properties.forEach(prop => {
        if (ts.isPropertyAssignment(prop)) {
          const key = getPropertyName(prop.name, sourceFile);
          obj[key] = evaluateNode(
            prop.initializer, sourceFile, variableDeclarations,
          );
        }
      });
      return obj;
    }
    case ts.SyntaxKind.ArrayLiteralExpression:
      return node.elements.map(
        el => evaluateNode(el, sourceFile, variableDeclarations),
      );
    default:
      return sourceFile.text.slice(node.getStart(sourceFile), node.getEnd());
  }
}

This is important because story files commonly extract shared arguments into variables or import them from helper files. For example, a story file might look like this:

import {sharedContent} from '../shared-args';

const meta: Meta = {
  id: 'components-button',
  title: 'Components/Button',
};

export default meta;

export const Primary: Story = {
  args: {
    variant: 'primary',
    label: 'Click me',
    'default-slot': sharedContent,
  },
};

export const Secondary: Story = {
  args: {
    variant: 'secondary',
    disabled: true,
    'default-slot': '<span>Custom content</span>',
  },
};

The plugin resolves the sharedContent import, walks the AST of the imported file, and inlines the value. After the plugin runs, the generated stories-manifest.json looks something like this:

{
  "version": "1.0.0",
  "totalComponents": 1,
  "totalStories": 2,
  "components": {
    "my-button": {
      "tagName": "my-button",
      "storyFile": "components/button/button.stories.ts",
      "schema": {
        "slots": [{"name": "default", "description": "The button content"}],
        "attributes": [
          {"name": "variant", "type": "string", "default": "'primary'"},
          {"name": "disabled", "type": "boolean", "default": "false"}
        ]
      },
      "stories": [
        {
          "name": "Primary",
          "storyId": "components-button--primary",
          "args": {"variant": "primary", "label": "Click me", "disabled": false},
          "slots": {"default": "<div>Shared slot content from import</div>"}
        },
        {
          "name": "Secondary",
          "storyId": "components-button--secondary",
          "args": {"variant": "secondary", "disabled": true},
          "slots": {"default": "<span>Custom content</span>"}
        }
      ]
    }
  }
}

With this manifest, you have everything needed to reconstruct the component in any environment. On the Next.js side, consuming it is straightforward. You can import the manifest and render each story’s component using its tag name, attributes and slot content:

'use client';

import React, { useMemo } from 'react'
import dynamic from 'next/dynamic'
import manifest from '@my-scope/components/stories-manifest.json'

/**
 * Create a dynamic component with server-side rendering support using next/dynamic.
 * The import path is derived from the tag name, so every component
 * in the library is loadable without a manual registry.
 */
function createDynamicComponent(
  tagName: string,
): React.ComponentType<Record<string, unknown>> | null {
  return dynamic(
    () => import(`@my-scope/components/${tagName}/${tagName}.js`),
    {ssr: true},
  );
}

export default function ComponentPreview({tagName, storyName}) {
  const component = manifest.components[tagName];
  const story = component?.stories.find(s => s.name === storyName);

  // Create a next/dynamic wrapper that supports server-side rendering
  const DynamicComponent = useMemo(
    () => createDynamicComponent(tagName),
    [tagName],
  );

  if (!story || !DynamicComponent) return null;

  // Build slot content from the manifest
  const slotContent = Object.entries(story.slots)
    .map(([name, content]) =>
      name === 'default'
        ? content
        : `<span slot="${name}">${content}</span>`,
    )
    .join('');

  return (
    <DynamicComponent {...story.args}>
      <span dangerouslySetInnerHTML={{__html: slotContent}} />
    </DynamicComponent>
  );
}

This gives us a 1:1 mirror of every Storybook story, rendered with Next.js and Server-Side Rendering. When a developer adds or modifies a story, we can reflect those changes in the Next.js test app and validate that it passes a series of tests.

<my-alert defer-hydration=""><template shadowroot="open" shadowrootmode="open"><style>
.my-alert {
  background: blue;
  color: white;
  padding: 1rem;
  border-radius: 4px;
  display: flex;
}
</style><!--lit-part ZtaKLkGwWx4=--><!--lit-node 0--><div class=" alert alert-info alert-type-basic " role="alert">
      <div class="alert-icon">
        <!--lit-node 2--><slot name="icon" ></slot>
      </div>
      <div class="alert-content">
        <!--lit-node 4--><slot name="header" ></slot>
        <slot></slot>
        <!--lit-node 6--><slot name="footer" ></slot>
      </div>
    </div><!--/lit-part--></template><span slot="header"><div>Notification Title</div></span><span slot="footer"></span></my-alert>

Hitting view-source on the Next.js page shows all the correct markers of server-side rendering.

Conclusion

What started as a simple idea to mirror Storybook stories in Next.js has turned into something with multiple applications. For example, you could use it to power your own documentation site without relying on Storybook’s embeds, or you could use it to feed your own MCP server to provide AI agents with a live catalogue of your components and their capabilities. This approach creates almost a “headless” Storybook, allowing you to keep your development flow the same while powering multiple outputs from that same source of truth.

Connecting the Custom Elements Manifest to Figma Code Connect

Jives — Mon, 27 Oct 2025 14:18:25 +0000

Something I've had on the back burner to implement for some time now is integration with Figma Code Connect. The benefit of using Code Connect is that you can specify how a Figma component translates into code, making it easier to hand off a design to a developer, as they'll know what component configuration in the design system to use right there in dev mode with usable snippets. Code Connect relies on code to make the initial translation, and, like any task, doing this manually is tedious and error-prone; therefore, if you're writing Web Components like me, it's worth exploring ways to automate the process using the ever-so-wonderful Custom Elements Manifest.

The Figma Code Connect API is not the most straightforward to work with. It has its quirks that can make integration challenging. The approach that Figma suggests is using their command line tool to generate a series of *.figma.ts files alongside your component declarations that map the Figma component to the code component. This is fine if you're working on a small project, but for larger projects with many components, this quickly becomes unmanageable as you have to keep these files in sync with your actual components. Fortunately, the Custom Elements Manifest provides a structured way to describe your web components, including their properties and slots. If you're already using it to generate your documentation, you can easily extend the generation process to also create the necessary Code Connect files on build.

For this to work effectively, you need to examine how your Figma components are set up. If your answer to any of the following is yes, plan some refactors to get the most out of Code Connect, as it will be challenging to automate the process.

Are the component properties in Figma and code in sync? For example, is your heading attribute on a component called something else in Figma?
Are all component abstractions represented? You might have split up a component in code, but it may be a single piece in Figma.
Are you missing icon names, variants, or other details?

Preparing Our Analyser

Most analysers that generate a Custom Elements Manifest operate by extending JSDoc comments. In our case, we'll need to add a @figma tag to our component comments so that we can tie the two together.
The URL provided here can be found by selecting the main component in Figma and copying the link. Both the file name and node-id are key pieces of information that we'll need to query the Figma API later.

/**
 * @customElement my-badge
 * A badge component for displaying status.
 * 
 * @figma https://www.figma.com/file/XOXZ/My-Design-System?node-id=123%3A456
 * @slot icon - Slot for the icon element.
 */
class MyBadge extends LitElement {
  /**
   * The label for the badge.
   */
  @property({type: String}) 
  public label: string = 'Badge';

  /**
   * The variant of the badge.
   */
  @property({type: String}) 
  public variant: 'positive' | 'negative' = 'positive';

  public override render(): TemplateResult {
    return html`<div class="badge ${this.variant}">
      <slot name="icon"></slot>
      ${this.label}
    </div>`;
  }
}

We'll use the @wc-toolkit/jsdoc-tags project to recognise the custom tag and then register our locally created code connect plugin, which we'll cover in the next section. As it's going to be a heavy task, we'll only set this to run when we analyse for our production publishes.

import {jsDocTagsPlugin} from '@wc-toolkit/jsdoc-tags';
import cemFigmaCodeConnectPlugin from './cem/cem-figma-code-connect-plugin.mjs';

export default {
  globs: [
    'src/ui/**/*.{js,ts}',
  ],
  outdir: bundleDir,
  litelement: true,
  dev: false,
  plugins: [
    jsDocTagsPlugin({
      tags: {
        figma: {
          description: 'Link to the components Figma page',
          mappedName: 'figma',
        },
      },
    }),
    // Only run Figma Code Connect plugin in production
    ...(process.env.NODE_ENV === 'production'
      ? [cemFigmaCodeConnectPlugin()]
      : []),
  ],
};

We'll also set up our figma.config.json file, which houses references to where our *.figma.ts files will eventually be located. This allows the CLI to scan the directory when the publishing job is ultimately run. You can find more information on how to configure this file here.

{
  "codeConnect": {
    "include": ["src/ui/**/*", "src/ui/**/*.figma.*"],
    "parser": "html",
    "importPaths": {
      "ui/**/*": "ui"
    },
    "paths": {
      "ui": ["src/ui"]
    },
    "documentUrlSubstitutions": {}
  }
}

Writing the Plugin

There are a couple of essential pieces of functionality that we'll need to consider with the plugin.

It must filter the components to process only those that have a custom @figma tag.
It must query the Figma Rest API to get the list of available properties on a component. Remember when I asked if your Figma properties were in sync with code? If you try to use something that doesn't exist in Figma, the validator will reject it. We'll need to reconcile any differences.
It must generate the necessary *.figma.ts files required for Code Connect.

We'll start by setting up the scaffold of our plugin, ensuring that only items with a @figma tag are processed.
As we run our plugin after the call to jsDocTagsPlugin, we can access the figma property on the declaration object.

export default function cemFigmaCodeConnectPlugin() {
  return {
    name: 'figma-code-connect-plugin',
    async packageLinkPhase({customElementsManifest}) {
      for (const mod of customElementsManifest.modules) {
        for (const declaration of mod.declarations) {
          // Only process components with attached Figma links
          if (declaration.figma?.name) {
            try {
              await generateCodeConnectFile(declaration, mod);
            } catch (error) {
              console.warn(
                `Failed to generate Code Connect for ${declaration.name}:`,
                error,
              );
            }
          }
        }
      }
    },
  };
}

Next, we'll extract the node-id parameter and file key from our Figma URLs and make a request to the file endpoint of the Figma API. After reading the Figma API documentation, calling the component endpoint would be the most obvious choice, yet, for some reason, the component endpoint doesn't contain the componentPropertyDefinitions object we need. There's probably a reason for it?

Here's what our method looks like.

async function getFigmaComponentProps(url) {
  const {FIGMA_ACCESS_TOKEN} = process.env;

  /**
   * Extract fileKey and nodeId from the Figma URL.
  */
  const {fileKey, nodeId} = parseFigmaUrl(url);

  try {
    /**
     * Get the specific node with component properties
    */
    const nodeUrl = `https://api.figma.com/v1/files/${fileKey}/nodes?ids=${nodeId}`;
    const nodeResponse = await fetch(nodeUrl, {
      headers: {'X-Figma-Token': FIGMA_ACCESS_TOKEN},
    });

    const nodeData = await nodeResponse.json();
    const node = nodeData.nodes?.[nodeId]?.document;
    let props = {};

    /**
     * For COMPONENT_SET, extract componentPropertyDefinitions
    */
    if (node.type === 'COMPONENT_SET' && node.componentPropertyDefinitions) {
      props = node.componentPropertyDefinitions;
    }

    return {props, node};
  } catch (error) {
    console.error('Error fetching Figma component props:', error);
    return {props: {}, node: null};
  }
}

With the list of component properties, we can then create a mapping between the attributes in the Custom Elements Manifest and Figma. The conversion here is pretty straightforward. We'll extract the attributes, normalise the Figma naming conventions by removing elements such as emojis, spaces, dashes, etc., and then map the two together if we determine they are equivalent. For example, 🖊️ Text would map to the text attribute in our manifest. It's essential that design and engineering speak the same language, but we should anticipate some form of deviation to accommodate stylistic choices.

async function generateCodeConnectFile(declaration, mod) {
  const figmaLink = declaration.figma?.name;

  const {
    props: figmaComponentProps,
    node: figmaNode,
    components: figmaComponents,
  } = await getFigmaComponentProps(figmaLink);

  const componentName = declaration.name
    .replace(/^My/, 'my-')
    .replace(/([a-z])([A-Z])/g, '$1-$2')
    .toLowerCase();

  const originalPath = mod.path;
  const filePath = mod.path.replace(/\.ts$/, '.figma.ts');

  /**
   * Get available attribute names from component declaration
   */
  const attrNames = new Set(declaration.attributes?.map(a => a.name) || []);

  /**
   * Maps Figma property names to component attribute names
   * @param {string} figmaName - Original Figma property name
   * @returns {string} Cleaned component compatible name
   */
  function mapFigmaNameToComponentName(figmaName) {
    return figmaName
      .replace(/^[^a-zA-Z]+/, '') // Remove emoji prefix
      .replace(/#\d+:\d+$/, '') // Remove ID suffix
      .toLowerCase()
      .replace(/\s+/g, '-'); // Convert spaces to hyphens
  }

  // Map and filter Figma properties to component attributes
  const mappedProps = {};
  const figmaPropNames = {};

  Object.entries(figmaComponentProps).forEach(([figmaName, def]) => {
    const componentName = mapFigmaNameToComponentName(figmaName);
    if (attrNames.has(componentName)) {
      mappedProps[componentName] = def;
      // Store clean Figma name for Code Connect
      figmaPropNames[componentName] = figmaName.replace(/#\d+:\d+$/, '');
    }
  });

  // Generate the Code Connect file content
  const content = generateCodeConnectContent({
    figmaLink,
    componentName,
    mappedProps,
    figmaPropNames,
  });

  await writeFile(filePath, content, 'utf8');
}

Lastly, we'll need to generate our *.figma.ts files and save them alongside our component definitions.

function generateCodeConnectContent({
  figmaLink,
  componentName,
  mappedProps,
  figmaPropNames,
}) {
  /**
  * Generate props object for Code Connect
  */
  const propsLines = Object.entries(mappedProps)
    .map(([componentName, def]) => {
      const figmaName = figmaPropNames[componentName];
      if (def.type === 'VARIANT') {
        const enumObj = Object.fromEntries(
          def.variantOptions.map(v => [v, v.toLowerCase()]),
        );
        return `${componentName}: figma.enum('${figmaName}', ${JSON.stringify(enumObj)}),`;
      } else if (def.type === 'BOOLEAN') {
        return `${componentName}: figma.boolean('${figmaName}'),`;
      } else {
        return `${componentName}: figma.string('${figmaName}'),`;
      }
    })
    .join('\n      ');

  const propsStr = propsLines ? `\n      ${propsLines}\n    ` : '';

  /**
  * Generate component attributes for the code samples
  */
  const exampleProps = Object.keys(mappedProps)
    .map(name => `${name}="\${props.${name}}"`)
    .join(' ');

  const componentTag = exampleProps 
    ? `<${componentName} ${exampleProps}></${componentName}>`
    : `<${componentName}></${componentName}>`;

  return `import figma, {html} from '@figma/code-connect/html';

figma.connect(
  '${figmaLink}',
  {
    props: {${propsStr}},
    example: props =>
      html\`${componentTag}\`,
  },
);
`;
}

When we run the analyser, we should now see the associated files being created. If all goes according to plan, you should now be able to run npx figma connect publish in your terminal to publish all of the code samples, if something is amiss, you'll get a validation error that should help you identify what needs to be fixed.

Here's an example of what one of the generated files looks like.

import figma, {html} from '@figma/code-connect/html';

figma.connect(
  'https://www.figma.com/design/XOXZ/My-Design-System?node-id=1-118&m=dev',
  {
    props: {
      variant: figma.enum('Variant', {
        Positive: 'positive',
        Negative: 'negative',
      }),
      label: figma.string('Label'),
    },
    example: props =>
      html`<my-badge variant="${props.variant}" label="${props.label}"></my-badge>`,
  },
);

You should instantly see your code samples reflected in Figma dev mode.

Instances and Slots

Web Components rely on slots for swapping inner pieces in and out of a component. In Figma, a similar concept exists in the form of instances.
The Figma API returns data about the component children, which we can use to compare against our available slots in the Custom Elements Manifest by filtering for an INSTANCE type.

function extractChildComponents(
  node,
  components = {},
  componentSlots = new Set(),
) {
  const children = [];

  if (!node.children) {
    return children;
  }

  for (const child of node.children) {
    /**
    * Look for INSTANCE children that represent actual slotted components
    */
    if (child.type === 'INSTANCE') {
      /**
      * Get the component definition if available
      */
      const componentDef = child.componentId
        ? components[child.componentId]
        : null;
      const componentName = componentDef?.name || child.name;

      children.push({
        name: child.name,
        componentName, // The actual component name from the components definition
        type: child.type,
        componentId: child.componentId,
        slotName: mapComponentNameToSlot(componentName, componentSlots),
      });
    }

    const nestedChildren = extractChildComponents(
      child,
      components,
      componentSlots,
    );
    children.push(...nestedChildren);
  }

  return children;
}

You'll then need to ensure that in the generated template, you're referencing the figma.instance or figma.children method with the appropriate name and then assigning that to an element with the proper slot name in your code examples. It's essential to understand the difference between these two methods:

You'd use figma.instance if:

You want to reference a specific named instance within the Figma component
The instance has a predictable, consistent name across variants
You need precise control over which instance maps to which slot
The component structure is simple, and instances are at the top level

Example: A button component where you always have a specific "Icon" instance that maps to an "icon" slot.

You'd use figma.children if:

You want to match instances by component type or naming pattern
The instance names vary across component variants but follow a pattern
You need to capture multiple instances of the same type
The instances are nested within variant components

For the most reliable results when mapping Figma instances to slots use consistent naming conventions and structural patterns in your Figma designs.
Where possible try to maintain a 1:1 mapping between slot names and instance names so that the analyser can automatically match them up.

import figma, {html} from '@figma/code-connect/html';

figma.connect(
  'https://www.figma.com/design/XOXZ/My-Design-System?node-id=1-118&m=dev',
  {
    props: {
      variant: figma.enum('Variant', {
        Positive: 'positive',
        Negative: 'negative',
      }),
      label: figma.string('Label'),
      icon: figma.children('Icon'),
    },
    example: props =>
      html`<my-badge variant="${props.variant}" label="${props.label}">
        <slot name="icon">${props.icon}</slot>
      </my-badge>`,
  },
);

figma.connect(
  'https://www.figma.com/design/XOXZ/My-Design-System?node-id=1-179&m=dev',
  {
    props: {
      icon: figma.enum('Icon', {
        x: 'x',
        y: 'y',
      }),
    },
    example: props => html`<my-icon icon="${props.icon}"></my-icon>`,
  },
);

In my opinion, is the most challenging part of implementing Code Connect for Web Components. You really need to make sure that not only are your property names aligned, but also the instances and how they are structured. There are numerous ways to approach tasks in Figma, and across an extensive library of components, the implementation is likely to be inconsistent. While automating this is technically possible, it's likely not practical and is very sensitive to naming and structural patterns, which may require manual intervention.

Conclusion

In general, I like the concept of Code Connect, but it requires very tight alignment across design and development, which may not be the reality for every team. However, even if you generate incomplete code samples, it's worthwhile, mainly if it provides visibility and directs users to your documentation to learn more, rather than having them to waste time implementing a component that already exists in your design system. Using the Custom Elements Manifest and the Figma REST API, you can create an approach that allows you to progressively improve the code samples over time each time the analyser script runs as you begin to refactor things. In my case, I decided to skip providing slot examples initially because they required major Figma refactors, but it's something I'd be keen to revisit in the future.

F45 Broke Their Strava Integration So I Wrote My Own

Jives — Sat, 15 Mar 2025 11:08:49 +0000

I've been going to F45 for over a year now, and it has completely changed my workout routine. I go almost every day, and I love it. I also love data and tracking my progression, so when they announced a Strava integration in 2024, I was very excited to use it. I wear the Lionheart monitor every time I go to track my heart rate and calories burned, and I love that it syncs to Strava so I can see my workouts in one place combined with my other exercises. However, since they updated to the Lionheart 2.0 system, they broke the Strava integration, and I'm not happy about it. Fortunately, where there's a will, there's a way.

It started off with the official integration randomly breaking on a Monday. I tried the usual troubleshooting steps, such as disconnecting and reconnecting my Strava account, but nothing worked.
After some digging, I found a support article on the F45 support page stating that it would be temporarily unavailable.

New and existing connections will not work at this time. We’ve decided to pause support for this feature and will revisit it at a later date.

Cool, I could live with temporarily, but eventually, that message was replaced with another and I wasn't sure if it would, or would not be eventually supported.

We’re no longer supporting Strava integration for now. As part of the Lionheart 2.0 update, we’ve made changes to our Strava integration, and it is no longer functional

It's baffling to me that such a new feature could be forgotten about so quickly, but knowing how product development works, I'm sure they have their reasons. I'm not going to sit around and wait for them to fix it, though. I want my data, and I want it now.

Getting The Data

This is the most unorthodox part of this whole process. There is no advertised public API for Lionheart that I know of or a functional website; the only place to get the data is the F45 mobile app. I used a Proxy to see if I could intercept the app's requests to their servers to find a usable payload. This process is similar to using the Network tab in Chrome's Developer Tools.

After digging around for a while and figuring out how to set up SSL proxying, I finally found the request containing the data I needed whenever I clicked on one of the workouts in the Lionheart tab.

Lo and behold, it contained everything I wanted, including calories burned, heart rates at given times, and even the workout name, in a nice JSON format. Turns out an API for Lionheart seems to exist but is undocumented for public use. Thankfully, I don't need any sort of credentials to query it, so nobody can stop me. Looking at the path, I tried to determine what data point each parameter was referring to.

https://api.lionheart.f45.com/v3/sessions/${CLASS_DATE}_${CLASS_TIME}:studio:${STUDIO_CODE}:serial:${LIONHEART_SERIAL_NUMBER}?user_id=${USER_ID}

I eventually figured out that I needed:

CLASS_DATE - The date of the class, for example, 2025-03-12.
CLASS_TIME - The time of the class, for example, 0630.
STUDIO_CODE - The studio code, which was easy to find in the response payload.
LIONHEART_SERIAL_NUMBER - The serial number on the back of the monitor.
USER_ID - The user ID, which was also in the response payload.

https://api.lionheart.f45.com/v3/profile/sessions/summary?user_id=${USER_ID}

I was also able to find another endpoint I could use which contained the profile, allowing me to maintain the same level of information for average scores and total sessions as the official integration did.

Building The Integration

Now that I have my data source, I need to upload it to Strava. Strava has an /upload endpoint that allows you to upload a workout using a .tcx formatted file. These files contain metadata about a workout, including the start time, duration, and heart rate data by timestamp. Converting the JSON data into a .tcx file is pretty simple; I just need to iterate over the data and format it correctly to match the schema. For this, I used the xmlbuilder library.

/**
 * Fetches the workout data from the Lionheart API.
*/
async function fetchJsonData(): Promise<ILionheartSession> {
  const CLASS_DATE = process.env.F45_CLASS_DATE;
  const STUDIO_CODE = process.env.F45_STUDIO_CODE;
  const USER_ID = process.env.F45_USER_ID;
  const LIONHEART_SERIAL_NUMBER = process.env.F45_LIONHEART_SERIAL_NUMBER;
  let CLASS_TIME = process.env.F45_CLASS_TIME;

  if (CLASS_TIME) {
    CLASS_TIME = CLASS_TIME.replace(":", "");
  }

  try {
    const url = `https://api.lionheart.f45.com/v3/sessions/${CLASS_DATE}_${CLASS_TIME}:studio:${STUDIO_CODE}:serial:${LIONHEART_SERIAL_NUMBER}?user_id=${USER_ID}`;
    const response = await fetch(url);

    if (!response.ok) {
      throw new Error(
        `Error fetching data from Lionheart API: ${response.statusText}`
      );
    }

    const data = (await response.json()) as ILionheartSession;

    return data;
  } catch (error) {
    console.error(`Failed to fetch data from Lionheart API: ${error} ❌`);
    throw error
  }
}

/**
 * Reformats the fetched data as a TCX file.
 */
function generateTcx(res: ILionheartSession): string {
  try {
    const { summary, graph } = res.data;
    const startTime = new Date(res.data.classInfo.timestamp * 1000);

    const root = create({ version: "1.0" })
      .ele("TrainingCenterDatabase", {
        xmlns: "http://www.garmin.com/xmlschemas/TrainingCenterDatabase/v2",
      })
      .ele("Activities")
      .ele("Activity", { Sport: "Other" })
      .ele("Id")
      .txt(startTime.toISOString())
      .up()
      .ele("Lap", { StartTime: startTime.toISOString() })
      .ele("TotalTimeSeconds")
      .txt((res.data.classInfo.durationInMinutes * 60).toString())
      .up()
      .ele("DistanceMeters")
      .txt("0")
      .up()
      .ele("Calories")
      .txt(summary.estimatedCalories.toString())
      .up()
      .ele("AverageHeartRateBpm")
      .ele("Value")
      .txt(summary.heartrate.average.toString())
      .up()
      .up()
      .ele("MaximumHeartRateBpm")
      .ele("Value")
      .txt(summary.heartrate.max.toString())
      .up()
      .up()
      .ele("Intensity")
      .txt("Active")
      .up()
      .ele("TriggerMethod")
      .txt("Manual")
      .up()
      .ele("Track");

    graph.timeSeries.forEach((entry) => {
      if (entry.type === "recordedBpm") {
        const timePoint = new Date(startTime.getTime() + entry.minute * 60000);
        if (entry.bpm) {
          root
            .ele("Trackpoint")
            .ele("Time")
            .txt(timePoint.toISOString())
            .up()
            .ele("HeartRateBpm")
            .ele("Value")
            .txt(entry.bpm.max.toString())
            .up()
            .up();
        }
      }
    });

    return root.end({ prettyPrint: true });
  } catch (error) {
    console.error(`Error generating TCX file: ${error} ❌`);
    throw error;
  }
}

The resulting .tcx file ends up looking something like this.

<?xml version="1.0" encoding="UTF-8"?>
<TrainingCenterDatabase xmlns="http://www.garmin.com/xmlschemas/TrainingCenterDatabase/v2"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://www.garmin.com/xmlschemas/TrainingCenterDatabase/v2 http://www.garmin.com/xmlschemas/TrainingCenterDatabasev2.xsd">
  <Activities>
    <Activity Sport="Other">
      <Id>2025-03-12T17:15:00</Id>
      <Lap StartTime="2025-03-12T17:15:00">
        <TotalTimeSeconds>2330</TotalTimeSeconds>
        <DistanceMeters>0.0</DistanceMeters>
        <MaximumSpeed>0.0</MaximumSpeed>
        <Calories>572</Calories>
        <AverageHeartRateBpm>
          <Value>141</Value>
        </AverageHeartRateBpm>
        <MaximumHeartRateBpm>
          <Value>160</Value>
        </MaximumHeartRateBpm>
        <Intensity>Active</Intensity>
        <TriggerMethod>Manual</TriggerMethod>
        <Track>
          <Trackpoint>
            <Time>2025-03-12T17:19:00Z</Time>
            <HeartRateBpm>
              <Value>98</Value>
            </HeartRateBpm>
          </Trackpoint>
          <Trackpoint>
            <Time>2025-03-12T17:20:00Z</Time>
            <HeartRateBpm>
              <Value>111</Value>
            </HeartRateBpm>
          </Trackpoint>
          <Trackpoint>
            <Time>2025-03-12T17:21:00Z</Time>
            <HeartRateBpm>
              <Value>116</Value>
            </HeartRateBpm>
          </Trackpoint>
          <Trackpoint>
            <Time>2025-03-12T17:22:00Z</Time>
            <HeartRateBpm>
              <Value>128</Value>
            </HeartRateBpm>
          </Trackpoint>
          <Trackpoint>
            <Time>2025-03-12T17:23:00Z</Time>
            <HeartRateBpm>
              <Value>143</Value>
            </HeartRateBpm>
          </Trackpoint>
          <Trackpoint>
            <Time>2025-03-12T17:24:00Z</Time>
            <HeartRateBpm>
              <Value>150</Value>
            </HeartRateBpm>
          </Trackpoint>
          <Trackpoint>
            <Time>2025-03-12T17:25:00Z</Time>
            <HeartRateBpm>
              <Value>149</Value>
            </HeartRateBpm>
          </Trackpoint>
          <Trackpoint>
            <Time>2025-03-12T17:26:00Z</Time>
            <HeartRateBpm>
              <Value>131</Value>
            </HeartRateBpm>
          </Trackpoint>
          <Trackpoint>
            <Time>2025-03-12T17:27:00Z</Time>
            <HeartRateBpm>
              <Value>129</Value>
            </HeartRateBpm>
          </Trackpoint>
          <Trackpoint>
            <Time>2025-03-12T17:28:00Z</Time>
            <HeartRateBpm>
              <Value>139</Value>
            </HeartRateBpm>
          </Trackpoint>
          <Trackpoint>
            <Time>2025-03-12T17:29:00Z</Time>
            <HeartRateBpm>
              <Value>148</Value>
            </HeartRateBpm>
          </Trackpoint>
          <Trackpoint>
            <Time>2025-03-12T17:30:00Z</Time>
            <HeartRateBpm>
              <Value>158</Value>
            </HeartRateBpm>
          </Trackpoint>
          <Trackpoint>
            <Time>2025-03-12T17:31:00Z</Time>
            <HeartRateBpm>
              <Value>152</Value>
            </HeartRateBpm>
          </Trackpoint>
          <Trackpoint>
            <Time>2025-03-12T17:32:00Z</Time>
            <HeartRateBpm>
              <Value>160</Value>
            </HeartRateBpm>
          </Trackpoint>
          <Trackpoint>
            <Time>2025-03-12T17:33:00Z</Time>
            <HeartRateBpm>
              <Value>160</Value>
            </HeartRateBpm>
          </Trackpoint>
          <Trackpoint>
            <Time>2025-03-12T17:34:00Z</Time>
            <HeartRateBpm>
              <Value>155</Value>
            </HeartRateBpm>
          </Trackpoint>
          <Trackpoint>
            <Time>2025-03-12T17:35:00Z</Time>
            <HeartRateBpm>
              <Value>151</Value>
            </HeartRateBpm>
          </Trackpoint>
          <Trackpoint>
            <Time>2025-03-12T17:36:00Z</Time>
            <HeartRateBpm>
              <Value>145</Value>
            </HeartRateBpm>
          </Trackpoint>
          <Trackpoint>
            <Time>2025-03-12T17:37:00Z</Time>
            <HeartRateBpm>
              <Value>150</Value>
            </HeartRateBpm>
          </Trackpoint>
          <Trackpoint>
            <Time>2025-03-12T17:38:00Z</Time>
            <HeartRateBpm>
              <Value>159</Value>
            </HeartRateBpm>
          </Trackpoint>
          <Trackpoint>
            <Time>2025-03-12T17:39:00Z</Time>
            <HeartRateBpm>
              <Value>160</Value>
            </HeartRateBpm>
          </Trackpoint>
          <Trackpoint>
            <Time>2025-03-12T17:40:00Z</Time>
            <HeartRateBpm>
              <Value>160</Value>
            </HeartRateBpm>
          </Trackpoint>
          <Trackpoint>
            <Time>2025-03-12T17:41:00Z</Time>
            <HeartRateBpm>
              <Value>154</Value>
            </HeartRateBpm>
          </Trackpoint>
          <Trackpoint>
            <Time>2025-03-12T17:42:00Z</Time>
            <HeartRateBpm>
              <Value>146</Value>
            </HeartRateBpm>
          </Trackpoint>
          <Trackpoint>
            <Time>2025-03-12T17:43:00Z</Time>
            <HeartRateBpm>
              <Value>148</Value>
            </HeartRateBpm>
          </Trackpoint>
          <Trackpoint>
            <Time>2025-03-12T17:44:00Z</Time>
            <HeartRateBpm>
              <Value>150</Value>
            </HeartRateBpm>
          </Trackpoint>
          <Trackpoint>
            <Time>2025-03-12T17:45:00Z</Time>
            <HeartRateBpm>
              <Value>152</Value>
            </HeartRateBpm>
          </Trackpoint>
          <Trackpoint>
            <Time>2025-03-12T17:46:00Z</Time>
            <HeartRateBpm>
              <Value>150</Value>
            </HeartRateBpm>
          </Trackpoint>
          <Trackpoint>
            <Time>2025-03-12T17:47:00Z</Time>
            <HeartRateBpm>
              <Value>152</Value>
            </HeartRateBpm>
          </Trackpoint>
          <Trackpoint>
            <Time>2025-03-12T17:48:00Z</Time>
            <HeartRateBpm>
              <Value>156</Value>
            </HeartRateBpm>
          </Trackpoint>
          <Trackpoint>
            <Time>2025-03-12T17:49:00Z</Time>
            <HeartRateBpm>
              <Value>157</Value>
            </HeartRateBpm>
          </Trackpoint>
          <Trackpoint>
            <Time>2025-03-12T17:50:00Z</Time>
            <HeartRateBpm>
              <Value>160</Value>
            </HeartRateBpm>
          </Trackpoint>
          <Trackpoint>
            <Time>2025-03-12T17:51:00Z</Time>
            <HeartRateBpm>
              <Value>158</Value>
            </HeartRateBpm>
          </Trackpoint>
          <Trackpoint>
            <Time>2025-03-12T17:52:00Z</Time>
            <HeartRateBpm>
              <Value>159</Value>
            </HeartRateBpm>
          </Trackpoint>
          <Trackpoint>
            <Time>2025-03-12T17:53:00Z</Time>
            <HeartRateBpm>
              <Value>157</Value>
            </HeartRateBpm>
          </Trackpoint>
          <Trackpoint>
            <Time>2025-03-12T17:54:00Z</Time>
            <HeartRateBpm>
              <Value>159</Value>
            </HeartRateBpm>
          </Trackpoint>
          <Trackpoint>
            <Time>2025-03-12T17:55:00Z</Time>
            <HeartRateBpm>
              <Value>153</Value>
            </HeartRateBpm>
          </Trackpoint>
          <Trackpoint>
            <Time>2025-03-12T17:56:00Z</Time>
            <HeartRateBpm>
              <Value>152</Value>
            </HeartRateBpm>
          </Trackpoint>
          <Trackpoint>
            <Time>2025-03-12T17:57:00Z</Time>
            <HeartRateBpm>
              <Value>155</Value>
            </HeartRateBpm>
          </Trackpoint>
        </Track>
      </Lap>
    </Activity>
  </Activities>
</TrainingCenterDatabase>

Now when the script runs, it will request an authorization code for the user, request the data from the Lionheart API, generate the .tcx file, and upload it.

/**
 * Gets a new access token from Strava, allowing us to make an API request.
 */
const getAccessToken = async (): Promise<IStravaTokenResponse> => {
  try {
    const response = await fetch(STRAVA_TOKEN_ENDPOINT, {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        grant_type: "refresh_token",
        refresh_token: STRAVA_REFRESH_TOKEN,
        client_id: STRAVA_CLIENT_ID,
        client_secret: STRAVA_CLIENT_SECRET,
      }),
    });

    if (!response.ok) {
      throw new Error(`Error fetching access token: ${response.statusText}`);
    }

    return response.json() as Promise<IStravaTokenResponse>;
  } catch (error) {
    console.error(`Failed to get access token: ${error} ❌`);
    throw error;
  }
};

/**
 * Uploads a TCX file to Strava.
 * The TCX file contains all of the information about the workout
 * including graph data, heart rates, and more.
 */
async function uploadTcxFile(
  accessToken: string,
  filePath: string,
  data: IStravaUploadParameters
) {
  try {
    const file = fs.createReadStream(filePath);
    const formData = new FormData();
    formData.append("file", file);
    formData.append("name", data.name);
    formData.append("description", data.description);
    formData.append("data_type", data.data_type);

    const response = await fetch(STRAVA_UPLOAD_ENDPOINT, {
      method: "POST",
      headers: {
        Authorization: `Bearer ${accessToken}`,
      },
      body: formData,
    });

    if (!response.ok) {
      const errorBody = await response.text();
      throw new Error(
        `Error uploading TCX file: ${response.statusText} - ${errorBody}`
      );
    }

    return response.json();
  } catch (error) {
    console.error(`Failed to upload TCX file: ${error} ❌`);
    throw error;
  }
}

As a result, I now have a workout similar to what I had before with the official integration in Strava. Sure, I'm missing a nice graphic that gets uploaded along with the workout, but I can live without that for now
as I have the same level of detail anyway.

I decided to take this one step further and convert the script into a reusable GitHub Action that I can manually trigger from a workflow. This way, I can run it whenever I want to upload a workout, including when traveling, for that extra bit of convenience. It also means that you can run this if you have all the information on hand.

name: Import F45 Lionheart Data to Strava 📊

on:
  workflow_dispatch:
    inputs:
      F45_CLASS_DATE:
        description: "The date of the F45 class you want to import (YYYY-MM-DD)"
        required: true
        default: "2023-01-01"
      F45_CLASS_TIME:
        description: "The time the class was scheduled that you want to import (HH:MM), 24-hour format"
        required: true
        default: "09:30"
      F45_STUDIO_CODE:
        description: "Override the stored environment variable for the studio code. This is useful if passporting at another studio."

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
      - name: Run Node.js script
        uses: JamesIves/f45-lionheart-strava-importer@main
        with:
          F45_CLASS_DATE: ${{ github.event.inputs.F45_CLASS_DATE }}
          F45_CLASS_TIME: ${{ github.event.inputs.F45_CLASS_TIME }}
          F45_STUDIO_CODE: ${{ github.event.inputs.STUDIO_CODE || secrets.F45_STUDIO_CODE }}
          F45_USER_ID: ${{ secrets.F45_USER_ID }}
          F45_LIONHEART_SERIAL_NUMBER: ${{ secrets.F45_LIONHEART_SERIAL_NUMBER }}
          STRAVA_REFRESH_TOKEN: ${{ secrets.STRAVA_REFRESH_TOKEN }}
          STRAVA_CLIENT_SECRET: ${{ secrets.STRAVA_CLIENT_SECRET }}
          STRAVA_CLIENT_ID: ${{ secrets.STRAVA_CLIENT_ID }}

Conclusion

I don't love that I have to do this, but I'm glad I can. Honestly, I wish F45 would fix this themselves because it's clear they have the data available, and it took me no time to get this working. While the app updates are nice and appreciated, I want to keep everything in one place.

Documenting Web Components With Storybook

Jives — Wed, 19 Feb 2025 16:39:54 +0000

Documentation is a crucial part of any design system. There's the aspect of writing, maintaining, and ensuring that it doesn't drift from the codebase. It's a lot of work, and it's easy to let it slip. I've spent a lot of time over the last year and a half thinking about the right way to document components, and it took some time until I found a sustainable solution I was happy with. In this article, I want to discuss how you can easily document your Web Components with Storybook so that your documentation provides a good user and developer experience.

Custom Elements Manifest

One of the best tools available in Web Component development is the Custom Elements Manifest. It's a JSON representation of all your available components, covering all the attributes, methods, slots and events they support, powered by your JSDoc comments and TypeScript types. You can customize the manifest generation through plugins to support custom JSDoc comments, allowing you to power more pieces of your documentation through code comments; for example, you could set up a comment format to indicate if your component is experimental or stable or provide a way to add a link to your Figma files.

import { LitElement, css, html } from "lit";
import { customElement, property } from "lit/decorators.js";

/**
 * The Button component, used for calling attention to actions.
 *
 * @customElement sb-button
 * @github https://github.com/starbucks/web-components
 * @figma https://figma.com
 *
 * @slot - The main content area of the button.
 * @csspart button - Allows you to style the button element.
 */
@customElement("sb-button")
export default class SBButton extends LitElement {
  /**
   * Determines the variant of the button.
   */
  @property({ type: String })
  public variant: "primary" | "secondary" = "primary";

  /**
   * Disables the button.
   */
  @property({ type: Boolean })
  public disabled?: boolean;

  /**
   * @inheritdoc
   */
  public render() {
    return html`
      <a
        part="button"
        ?disabled=${this.disabled}
        class="${this.variant === "primary" ? "primary" : "secondary"}"
      >
        <span><slot></slot> </span>
      </a>
    `;
  }

  static styles = css``;
}

declare global {
  interface HTMLElementTagNameMap {
    "sb-button": SBButton;
  }
}

My favourite Custom Elements Manifest generator is the one by open-wc. The setup is straightforward: you create a config file and tell it where to find your components. It even has support for Lit out of the box.

import { jsDocTagsPlugin } from "@wc-toolkit/jsdoc-tags";

export default {
  globs: ["src/components/**/*.ts"],
  outdir: "public",
  litelement: true,
  dev: false,
  plugins: [
    jsDocTagsPlugin({
      tags: {
        figma: {
          description: "Link to the Figma design",
          type: "string",
          tagMapping: "figma",
        },
        github: {
          description: "Link to the GitHub repo",
          type: "string",
          tagMapping: "github",
        },
      },
    }),
  ],
};

After you've generated the Custom Elements Manifest, you'll see how vast the dataset is. You're creating a payload that lets you query all the intricate details about your components, which is ideal for automatically generating documentation.

{
  "schemaVersion": "1.0.0",
  "readme": "",
  "modules": [
    {
      "kind": "javascript-module",
      "path": "src/components/sb-button/sb-button.stories.ts",
      "declarations": [
        {
          "kind": "variable",
          "name": "meta",
          "type": {
            "text": "Meta<SBButton>"
          },
          "default": "{ title: \"Components/Button\", component, args, argTypes, parameters: { actions: { handles: events, }, }, render: (args) => template(args), }"
        },
        {
          "kind": "variable",
          "name": "Secondary",
          "type": {
            "text": "Story"
          },
          "default": "{ args: { \"default-slot\": \"Secondary Button\", variant: \"secondary\", }, }"
        },
        {
          "kind": "variable",
          "name": "Primary",
          "type": {
            "text": "Story"
          },
          "default": "{ args: { \"default-slot\": \"Primary Button\", variant: \"primary\", }, }"
        }
      ],
      "exports": [
        {
          "kind": "js",
          "name": "default",
          "declaration": {
            "name": "meta",
            "module": "src/components/sb-button/sb-button.stories.ts"
          }
        },
        {
          "kind": "js",
          "name": "Secondary",
          "declaration": {
            "name": "Secondary",
            "module": "src/components/sb-button/sb-button.stories.ts"
          }
        },
        {
          "kind": "js",
          "name": "Primary",
          "declaration": {
            "name": "Primary",
            "module": "src/components/sb-button/sb-button.stories.ts"
          }
        }
      ]
    },
    {
      "kind": "javascript-module",
      "path": "src/components/sb-button/sb-button.ts",
      "declarations": [
        {
          "kind": "class",
          "description": "The Button component, used for calling attention to actions.",
          "name": "SBButton",
          "cssParts": [
            {
              "description": "Allows you to style the button element.",
              "name": "button"
            }
          ],
          "slots": [
            {
              "description": "The main content area of the button.",
              "name": ""
            }
          ],
          "members": [
            {
              "kind": "field",
              "name": "variant",
              "type": {
                "text": "\"primary\" | \"secondary\""
              },
              "privacy": "public",
              "default": "\"primary\"",
              "description": "Determines the variant of the button.",
              "attribute": "variant"
            },
            {
              "kind": "field",
              "name": "disabled",
              "type": {
                "text": "boolean | undefined"
              },
              "privacy": "public",
              "description": "Disables the button.",
              "attribute": "disabled"
            }
          ],
          "attributes": [
            {
              "name": "variant",
              "type": {
                "text": "\"primary\" | \"secondary\""
              },
              "default": "\"primary\"",
              "description": "Determines the variant of the button.",
              "fieldName": "variant"
            },
            {
              "name": "disabled",
              "type": {
                "text": "boolean | undefined"
              },
              "description": "Disables the button.",
              "fieldName": "disabled"
            }
          ],
          "superclass": {
            "name": "LitElement",
            "package": "lit"
          },
          "tagName": "sb-button",
          "customElement": true,
          "github": {
            "name": "https://github.com/starbucks/web-components",
            "description": ""
          },
          "figma": {
            "name": "https://figma.com",
            "description": ""
          }
        }
      ],
      "exports": [
        {
          "kind": "js",
          "name": "default",
          "declaration": {
            "name": "SBButton",
            "module": "src/components/sb-button/sb-button.ts"
          }
        },
        {
          "kind": "custom-element-definition",
          "name": "sb-button",
          "declaration": {
            "name": "SBButton",
            "module": "src/components/sb-button/sb-button.ts"
          }
        }
      ]
    },
    {
      "kind": "javascript-module",
      "path": "src/components/sb-card/sb-card.stories.ts",
      "declarations": [
        {
          "kind": "variable",
          "name": "meta",
          "type": {
            "text": "Meta<SBCard>"
          },
          "default": "{ title: \"Components/Card\", component, args, argTypes, parameters: { actions: { handles: events, }, }, render: (args) => template(args), }"
        },
        {
          "kind": "variable",
          "name": "Secondary",
          "type": {
            "text": "Story"
          },
          "default": "{ args: { \"header-slot\": \"<h2>About Us</h2>\", \"body-slot\": \"<p>Find out more about our company and heritage.</p>\", \"image-slot\": \"<img src='https://www.starbucks.co.uk/sites/starbucks-uk-pwa/files/styles/c22_featured_card_531x273/public/2022-03/About%20us%20-%20Starbucks%20%281%29.jpg?h=78ab6d9e&itok=EjamtVRd' alt='Starbucks' />\", \"footer-slot\": \"<sb-button variant='primary'>Order Now</sb-button>\", variant: \"secondary\", }, }"
        },
        {
          "kind": "variable",
          "name": "Primary",
          "type": {
            "text": "Story"
          },
          "default": "{ args: { \"header-slot\": \"<h2>Meet your new favourits!</h2>\", \"body-slot\": \"<p>Our new Iced Shaken Espresso is the perfect way to cool down this summer.</p>\", \"image-slot\": \"<img src='https://www.starbucks.co.uk/sites/starbucks-uk-pwa/files/styles/c22_featured_card_531x273/public/2025-01/3469%20UK%20WIN25%20Web%20Banners%20-%20C22%20LTO%20Banner%20727x373px_v01.png?h=aec870e8&itok=BhZ99vG8' alt='Starbucks' />\", \"footer-slot\": \"<sb-button variant='secondary'>Order Now</sb-button>\", variant: \"primary\", }, }"
        }
      ],
      "exports": [
        {
          "kind": "js",
          "name": "default",
          "declaration": {
            "name": "meta",
            "module": "src/components/sb-card/sb-card.stories.ts"
          }
        },
        {
          "kind": "js",
          "name": "Secondary",
          "declaration": {
            "name": "Secondary",
            "module": "src/components/sb-card/sb-card.stories.ts"
          }
        },
        {
          "kind": "js",
          "name": "Primary",
          "declaration": {
            "name": "Primary",
            "module": "src/components/sb-card/sb-card.stories.ts"
          }
        }
      ]
    },
    {
      "kind": "javascript-module",
      "path": "src/components/sb-card/sb-card.ts",
      "declarations": [
        {
          "kind": "class",
          "description": "This component is used to create a card that can be utilized to call attention to important marketing opportunities,\nsuch as promotions, new product launches, or special events. It is also ideal for highlighting new drinks or menu items\nfor customers to order. The card is designed to be visually appealing and can include an image, header, body, and footer content.",
          "name": "SBCard",
          "slots": [
            {
              "description": "Slot for the primary card image.",
              "name": "image"
            },
            {
              "description": "Slot for the card header.",
              "name": "header"
            },
            {
              "description": "Slot for the card body.",
              "name": "body"
            },
            {
              "description": "Slot for the card footer.",
              "name": "footer"
            }
          ],
          "members": [
            {
              "kind": "field",
              "name": "variant",
              "type": {
                "text": "\"primary\" | \"secondary\""
              },
              "privacy": "public",
              "default": "\"primary\"",
              "description": "Copy for the read the docs hint.",
              "attribute": "variant"
            }
          ],
          "attributes": [
            {
              "name": "variant",
              "type": {
                "text": "\"primary\" | \"secondary\""
              },
              "default": "\"primary\"",
              "description": "Copy for the read the docs hint.",
              "fieldName": "variant"
            }
          ],
          "superclass": {
            "name": "LitElement",
            "package": "lit"
          },
          "tagName": "sb-card",
          "customElement": true,
          "github": {
            "name": "https://github.com/starbucks/web-components",
            "description": ""
          },
          "figma": {
            "name": "https://figma.com",
            "description": ""
          }
        }
      ],
      "exports": [
        {
          "kind": "js",
          "name": "default",
          "declaration": {
            "name": "SBCard",
            "module": "src/components/sb-card/sb-card.ts"
          }
        },
        {
          "kind": "custom-element-definition",
          "name": "sb-card",
          "declaration": {
            "name": "SBCard",
            "module": "src/components/sb-card/sb-card.ts"
          }
        }
      ]
    }
  ]
}

So many good plugins for the generator allow you to enhance the developer experience for those using your components. For instance, you can enable VSCode IDE highlighting on your custom elements using the custom-element-vs-code-integration plugin and generate TypeScript mappings for those using your components in JSX with custom-element-jsx-integration. Getting the most out of the Custom Elements Manifest depends on how well you comment and type your codebase, which we should all strive to improve anyway.

Wiring the Controls

Storybook Controls is one of the best features of Storybook, but it's also one I've seen teams struggle with the most. If you've wired up your story to include all of the available parameters, it will build an interface that allows your users to toggle things on and off to see how the component reacts in real time. This feature is super helpful as it will enable your users to understand your component API better and how things work before they implement it in their application. It also helps QA teams test your components more effectively.

The problem, however, is that this is quite cumbersome to maintain. If you do this manually, you'll end up where things are often broken or left out of the table unless you have exceptional discipline. Most of the feedback I've gotten from teams struggling with Storybook is that this is their biggest pain point; however, using the Custom Elements Manifest file we generated, there's a better way, as it already knows everything about our components.

const meta: Meta<SBButton> = {
  title: "Components/Button",
  component,
  argTypes: {
    variant: {
      options: ["primary", "secondary"],
      control: { type: "radio" },
    },
  },
  render: (args) => html`<sb-button .variant=${args.variant}></sb-button>`,
};

export default meta;

Imagining having to maintain the argTypes object for EVERY parameter?

Wiring up your stories to read from the Custom Elements Manifest is a matter of creating a function that parses it, outputs the correct schema Storybook expects, and then spreads any attributes directly onto your component. We'll need to provide the methods with the associated element name at a minimum so it knows what to key off of. I've put together a small example of what this could look like.

function getArgTypesFromManifest(manifest: Manifest, componentName: string) {
  const module = manifest.modules.find((mod) =>
    mod.declarations.some((decl) => decl.tagName === componentName)
  );

  if (!module) return {};

  const declaration = module.declarations.find(
    (decl) => decl.tagName === componentName
  );

  if (!declaration) return {};

  const argTypes: Record<string, ArgType> = {};

  declaration.attributes.forEach((attr) => {
    argTypes[attr.name] = {
      control: { type: getControlType(attr.type.text) },
      description: attr.description,
      defaultValue: attr.default,
      options: getOptions(attr.type.text),
    };
  });

  return { argTypes };
}

function getControlType(type: string): string {
  if (type.includes("|")) {
    return "select";
  }
  switch (type) {
    case "string":
      return "text";
    case "number":
      return "number";
    case "boolean":
      return "boolean";
    default:
      return "text";
  }
}

function getOptions(type: string): string[] {
  if (type.includes("|")) {
    return type.split("|").map((option) => option.trim().replace(/"/g, ""));
  }
  return [];
}

Maintaining this code yourself can be challenging as there's a lot of nuance in how things are defined in the manifest file. Instead of writing this yourself, I recommend using this excellent plugin from Burton Smith, which handles this piece for you. Using this plugin, you can manipulate CSS variables, slots and other things directly from Storybook controls with minimal boilerplate. It's fantastic, and everyone should use it; seriously, don't write this yourself; it's much better with the plugin.

import type { Meta, StoryObj } from "@storybook/web-components";
import SBButton from "./sb-button";
import { getWcStorybookHelpers } from "wc-storybook-helpers";
import "./sb-button";

const component = "sb-button";
const { events, args, argTypes, template } = getWcStorybookHelpers(component);
type Story = StoryObj<SBButton & typeof args>;

const meta: Meta<SBButton> = {
  title: "Components/Button",
  component,
  args,
  argTypes,
  parameters: {
    actions: {
      handles: events,
    },
  },
  render: (args) => template(args),
};
export default meta;

export const Primary: Story = {
  args: {
    "default-slot": "Primary Button",
  },
};

With your controls automatically generating, you can now focus on writing high-quality code and comments without worrying about Storybook.

To reduce any setup fatigue, I add a *.stories.ts file alongside my component generator, which sets up everything the plugin needs to start automating Storybook Controls from day 0.

Docs

When it comes to documentation, you must understand your audience. That's not just those viewing your documentation but also those writing it. While having a fancy documentation site is excellent, maintaining one takes a lot of work. It's also not easy to break habits; if most of your users are visiting your Storybook already, they'll likely continue to do so even after you launch your new site, so wouldn't it be better to meet them where they are? If you don't have specific requirements, Storybook Docs will likely suffice as the vessel for your documentation for your designers and engineers. Your engineers can continue to have their documentation automatically generated while your designers and product owners can contribute with markdown.

My approach to documenting in Storybook is to have a template that applies to everything by default, with a simple way to provide manually injected content where it makes sense. To do this, I first set up a documentation template; setting up a template can be done by extending your Storybook configuration and pointing it towards a markdown file.

import type { Preview } from "@storybook/web-components";
import { setCustomElementsManifest } from "@storybook/web-components";
import customElements from "./custom-elements.json";
import DocumentationTemplate from "./DocumentationTemplate.mdx";

setCustomElementsManifest(customElements);

const preview: Preview = {
  tags: ["autodocs"],
  parameters: {
    docs: {
      template: DocumentationTemplate,
    },
    controls: {
      expanded: true,
      matchers: {
        color: /(background|color)$/i,
        date: /Date$/i,
      },
    },
  },
};

export default preview;

Out of the box, Storybook has several documentation-orientated components you can use, which they call blocks. You use them to display things like the component title, description, and the controls we created earlier.

import { Meta, Title, Primary, Controls, Stories } from '@storybook/blocks';


<Meta isTemplate />

<Title />

# Default implementation

<Primary />

## Inputs

The component accepts the following inputs (props):

<Controls />

---

## Additional variations

Listed below are additional variations of the component.

<Stories />

Many of these out-of-the-box components, however, don't fit the bill. We want our Custom Elements Manifest to drive our documentation; it's no good if we define a bunch of custom JSDoc comments if they aren't used in our documentation, right? Fortunately, Storybook provides a way to define your own custom blocks using the of hook. Using this hook, we can tap into the metadata provided by our story to get the component name; we can then fetch the Custom Elements Manifest JSON file and pull data directly from it into our documentation. We can use this technique to set up instructions on installing our component or a list of badges based on what the component supports. More importantly, you can use your own design system elements to make everything look ✨ official ✨.

import { useOf, Markdown } from '@storybook/blocks';
import React from 'react';

/**
 * Renders an install block for a component.
 */
const Install = ({ of }) => {
  const resolvedOf = useOf(of || 'story', ['story', 'meta']);
  let componentName = '';

  switch (resolvedOf.type) {
    case 'story': {
      componentName = resolvedOf.story.component
      break;
    }
    default: {
      componentName = '';
    }
  }

  const markdown = `\`\`\`javascript
      npm install @starbucks/${componentName.toLowerCase().replace(/\s+/g, '-')}
    \`\`\``;

  return <Markdown>{markdown}</Markdown>;
};

export default Install

import React, { useEffect, useState } from 'react';
import { Title as BlocksTitle, useOf } from '@storybook/blocks';
import { GitHubLogo, FigmaLogo } from './Logos';

/**
 * Renders a title block for a component, including any associated GitHub and Figma links.
 */
const Title = ({ of }) => {
  const [componentName, setComponentName] = useState('');
  const [githubLink, setGithubLink] = useState('');
  const [figmaLink, setFigmaLink] = useState('');

  const resolvedOf = useOf(of || 'story', ['story', 'meta']);

  useEffect(() => {
    const fetchComponentData = async () => {
      let componentName = '';

      switch (resolvedOf.type) {
        case 'story': {
          componentName = resolvedOf.story.component;
          break;
        }
        default: {
          componentName = '';
        }
      }

      setComponentName(componentName);

      try {
        const response = await fetch('/public/custom-elements.json');
        const manifest = await response.json();
        const component = manifest.modules.find(module => module.declarations.some(declaration => declaration.tagName === componentName));
        if (component) {
          const declaration = component.declarations.find(declaration => declaration.tagName === componentName);
          if (declaration.github) {
            setGithubLink(declaration.github.name);
          }
          if (declaration.figma) {
            setFigmaLink(declaration.figma.name);
          }
        }
      } catch (error) {
        console.error('Error fetching JSON:', error);
      }
    };

    fetchComponentData();
  }, [resolvedOf]);

  return (
    <div style={{ display: 'flex', justifyContent: 'space-between', alignItems: 'center' }}>
      <BlocksTitle />
      <div style={{ display: 'flex', gap: '10px' }}>
        {githubLink && (
          <a href={githubLink} target="_blank" rel="noopener noreferrer">
            <GitHubLogo />
          </a>
        )}
        {figmaLink && (
          <a href={figmaLink} target="_blank" rel="noopener noreferrer">
            <FigmaLogo />
          </a>
        )}
      </div>
    </div>
  );
};

export default Title;

You can then update your default documentation template to reference these components.

import { Meta, Description,  Primary, Controls, Stories } from '@storybook/blocks';
import Install from './blocks/Install';
import Title from './blocks/Title';


<Meta isTemplate />

<Title />
<Description />
<Install />

<Primary />

## Inputs

The component accepts the following inputs (props):

<Controls />

With this setup, you can now automatically generate documentation that is consistent and up-to-date with your codebase.

Similarly, you can use these same components in your own manually created documentation pages for cases where the template does not provide enough details. Create a .mdx file alongside your component definition, so long as you tell Storybook what component it's associated with, it will use it over the default template.
Depending on how savvy your contributors are you may want to consider abstracting the full template into its own component, this way you can provide a consistent experience across all your documentation pages, while still allowing slotted areas for curated content.

import { Meta, Description,  Primary, Controls, Stories } from '@storybook/blocks';
import Install from './blocks/Install';
import Title from './blocks/Title';
import SBCardStories from './sb-card.stories.ts';

<Meta of={SBCardStories} />

<Title />
<Description />
<Install />


<Primary />

## Inputs

The component accepts the following inputs (props):

<Controls />

# Usage Considerations

## Do

- Use this component for displaying cards in a grid.
- Use this component for displaying cards in a list.

## Don't

- Use this component for displaying cards in a carousel.
- Use this component for displaying cards in a modal.

If you want to roll a custom documentation site, you can use the Custom Elements Manifest in the same way and even combine it with the outputted "stories.json" file, which I talked about in my Playwright article. This way, you can generate pages for each component while automatically embedding any valid Storybook stories. Ultimately, what you end up doing depends on your priorities and what you value more, and in some cases, I've found the simple route to be most palatable.

Third-party documentation platforms can be a challenge; if the tool provides no route to automation it may not be adopted by those intended to maintain it despite how rich their feature set may seem.

Conclusion

Meet your users where they are, either in the IDE, Storybook or Figma. Your documentation should be predictable, consistent, and, more importantly, accessible. You are building a product for users; if they can't find what they are looking for, they'll simply go elsewhere. Work smarter, not harder,
use the tools at your disposal.

Virtually Infinite Scrolling with Angular

Jives — Tue, 07 Jan 2025 12:05:18 +0000

Infinite scrollers have been around for a long time. The concept is simple: as you scroll down the page, additional content is fetched and added to the bottom, making it so the scrolling never ends. Implementing an infinite scroller is straightforward, but you might negatively affect page performance without careful consideration. By the time you've re-fetched content a few times, you could have hundreds of elements in the DOM that aren't even visible all at the same time. Fortunately, there are some patterns you can implement to avoid this, some of which we'll cover in this article using Angular.

Ideally we want to avoid this.

Virtual Scrolling

Virtual Scrolling is a technique used to render a subset of an extensive list of items at any given time, not to be confused with Infinite Scrolling. This technique is advantageous when you have a large dataset that you want to display in a list, but you don't want to render all of the items at once. Instead, you only render the currently visible items in the viewport (and those almost visible), and as the user scrolls, you dynamically swap out the contents of the nodes. Virtual Scrolling can improve performance by reducing the number of DOM elements that need to be rendered and updated at any time.

How Virtual Scrolling works is pretty straightforward: we create a container that is the viewport's height and only render the items currently visible (along with a buffer) within that container at the given scroll depth from memory. As the user scrolls, we update the container to show the next set of items and remove the items that are no longer visible while increasing and decreasing the scroll depth using CSS. Suppose we combine this concept with an infinite scroller. In that case, we can create a scrollable list that can be virtually infinite in length without negatively affecting performance as we increase the maximum depth every time more content is added.

The following sample has a list of items well into the thousands, but as you can see, we only render a maximum of 8 elements. As we scroll, we adjust the CSS to change the scroll height to give the illusion of a long list.

Real World Example

Let's build an example to demonstrate how you might implement a Virtual Scroller in Angular. We'll make a simple application that fetches media content from Reddit's paginated API and displays it in a list. The application will have a search bar that allows you to type in a subreddit name to change the retrieved content list and a way to apply a filter. As you scroll down the page, the service adds additional content to the bottom. Our high-level requirements are as follows:

RxJs Observables and the async pipe should drive it.
It should reset content whenever the subreddit name or filter changes. It should not reset when we append new content.
It should store prior content in memory so we can scroll back up and down without making unnecessary API requests.

We'll need to install the @angular/cdk package, which contains a Virtual Scroller component as part of Angular's Component DevKit. You can do this by running npm i @angular/cdk.

While the following example uses Angular, there's no reason you can't implement a similar pattern in other frameworks, such as React, Vue, or even vanilla JavaScript. I've assembled a small demo of what this might look like under the hood that you can view here.

Setting Up The Service

First, we must set up a service that can fetch content from Reddit's API. We'll use Angular's HttpClient to make the request and set up a few RxJs observables to hold the state for the requested subreddit name and filter. I've omitted some of the code for brevity, but you can find the full implementation here.

@Injectable({
  providedIn: 'root'
})
export class RedditService {
  private static readonly API_BASE = 'https://www.reddit.com/r'
  private static readonly MAX_CONTENT_FETCH = 24
  private static readonly DEFAULT_SUBREDDIT = 'cats'
  private static readonly DEFAULT_PAGE = 't3_'

  /**
   * We'll implement _query$ later in the article.
   */
  private readonly _query$: Observable<IRedditQuery>


  /**
   * BehaviorSubject which houses the current subreddit name.
   */
  private readonly _subRedditName$ = new BehaviorSubject(
    RedditService.DEFAULT_SUBREDDIT
  )

  /**
   * BehaviorSubject which houses the current page.
   */
  private readonly _subRedditPage$ = new BehaviorSubject(
    RedditService.DEFAULT_PAGE
  )

  /**
   * BehaviorSubject which houses the currently set filter.
   */
  private readonly _subRedditFilter$ = new BehaviorSubject(RedditFilter.HOT)

  /**
   * Sets the name of subreddit, for example 'cats' or 'fish'.
   * @param name The name of the subreddit.
   */
  public setSubRedditName(name: string): void {
    /**
    * Whenever the subreddit name changes we reset the page to the default.
    */
    this.setSubRedditPage(RedditService.DEFAULT_PAGE)

    this._subRedditName$.next(name)
  }

  /**
   * Sets the name of the page to display. The Reddit API allows you to specify
   * at which point you want to fetch after. As a result we index the page name
   * after each fetch and use it to fetch the next set of paginated content.
   * @param page The name of the page to fetch content after.
   */
  public setSubRedditPage(page: string): void {
    this._subRedditPage$.next(`${RedditService.DEFAULT_PAGE}${page}`)
  }

  /**
   * Sets the name of the subreddit filter, for example 'hot' or 'new'.
   * @param filter The name of the filter {@see RedditFilter} for options.
   */
  public setSubRedditFilter(filter: RedditFilter): void {
    /** On each filter change reset the page back to default value
     * to prevent lingering pages. */
    this.setSubRedditPage(RedditService.DEFAULT_PAGE)

    this._subRedditFilter$.next(filter)
  }

  /**
   * Gets the sub reddit name option as an observable.
   * @returns An observable that contains the currently set name.
   */
  public getSubRedditName(): Observable<string> {
    return this._subRedditName$.asObservable()
  }

  /**
   * Gets the current page being viewed as an observable.
   * @returns An observable that can contains the currently set page.
   */
  public getSubRedditPage(): Observable<string> {
    return this._subRedditPage$.asObservable()
  }

  /**
   * Gets the sub reddit filter option as an observable.
   * @returns An observable that can translate the currently set filter option.
   */
  public getSubRedditFilter(): Observable<RedditFilter> {
    return this._subRedditFilter$.asObservable()
  }


  /**
   * Gets the current data requested from the Reddit API as an observable.
   * @returns An observable that contains the filtered content from the Reddit API.
   */
  public getQuery(): Observable<IRedditQuery> {
    return this._query$
  }
}

The method for implementing content fetching needs to track specific properties while requesting more data. We are adding a page property to the query string, which is essential to ensure we make a new request for content after the last item in the current set. Additionally, we filter out unwanted content from our stream, such as NSFW (not safe for work) material and content lacking a post hint. This approach guarantees we only provide content we expect to display in our component.

/**
 * Gets data from the Reddit API based on a series of defined filtering options.
 * @returns Returns an observable containing the data formatted as {@see IRedditResult}
*/
private getSubRedditContent({
  name,
  filter,
  page
}: IRedditRequestOptions): Observable<IRedditResult[]> {
  const path = new URL(`${RedditService.API_BASE}/${name}/${filter}/.json`)
  path.searchParams.append(
    RedditRequestParameters.LIMIT,
    RedditService.MAX_CONTENT_FETCH.toString()
  )

  // If page is provided it gets appended to the query to ensure we're not re-fetching the same content.
  if (page) {
    path.searchParams.append(RedditRequestParameters.AFTER, page)
  }

  console.info('✅ Making request to:', path.toString())

  return this.http.get<IRedditResultNatural>(path.toString()).pipe(
    map(result =>
      result.data.children
        .map(item => item.data)
        .filter(
          (item: IRedditResult) =>
            !item.over_18) &&
            item.post_hint &&
            ((item.post_hint === RedditPostHint.LINK &&
              item.secure_media_embed &&
              item.secure_media_embed.media_domain_url) ||
              item.post_hint === RedditPostHint.IMAGE ||
              item.post_hint === RedditPostHint.RICH_VIDEO)
        )
    )
  )
}

You may have noticed in the above examples that we were missing the implementation for the query$ observable. We'll use this as the central machinery for the entire application, which is ultimately what the Virtual Scroller component will subscribe to. The following sample code merges the different observable streams into one before fetching content. We then use the scan operator to integrate the previous stream results with the current one, creating an extensive array of data spanning multiple pages.

The idea behind this is that you can scroll as much as you like, and only in cases where the subreddit name or filter changes do we re-fetch entirely to get a fresh list of content. We also set nextPage as a property of the query$ stream, which matches the last item ID in the current set. This is used later in our component to determine what page of content to fetch when we're nearing the bottom of the Virtual Scroller.

 public constructor(private readonly http: HttpClient) {
    this._query$ = combineLatest([
      this.getSubRedditName(),
      this.getSubRedditFilter(),
    ]).pipe(
      switchMap(([name, filter]) =>
        this.getSubRedditPage().pipe(
          mergeMap(page =>
            this.getSubRedditContent({
              name,
              filter,
              page
            }).pipe(
              catchError(() => {
                /**
                 * If the stream catches an error return an empty array.
                 * For the sake of this demo we'll just assume that the subreddit
                 * has no content if it doesn't exist.
                 */
                return of([])
              })
            )
          ),

          /**
           * If the page observable emits instead of creating a new list it
           * will instead concat the previous results together with the new ones.
           * This is used for infinite scrolling pagination.
           */
          scan(
            (acc, curr) => {
              const newResults = curr.filter(
                item =>
                  !acc.results.some(existingItem => existingItem.id === item.id)
              )

              return {
                results: acc.results.concat(newResults),
                nextPage: curr[curr.length - 1]?.id
              }
            },
            {
              results: [] as IRedditResult[],
              nextPage: undefined
            } as IRedditQuery
          ),
          /**
           * Whenever a user requests a fresh set of content (ie changing the filter, subfilter, subreddit, etc)
           * we start with an empty array to prevent lingering content from previous pages.
           * It also gives instant feedback to the user that new content is being fetched by clearing the list.
           */
          startWith({results: [], nextPage: undefined} as IRedditQuery)
        )
      )
    )
  }

While all this logic may initially seem confusing, the advantage of using RxJs is that you can combine and manipulate data streams, which allows us to perform all of our business logic before it reaches our component. It also means that all the mechanisms are housed outside the component, allowing us to reuse the same data in another part of the application by subscribing to the same observable. I've found that learning RxJs has been the key to getting more comfortable with Angular; I now prefer Angular over any other front-end framework, as the patterns it introduces when working with them together make a lot of sense to me after I became more familiar with them.

Setting Up The Component

The next step is to set up the component to display the content in the Virtual Scroller. We'll use Angular's CdkVirtualScrollViewport component to render the content and set up a method for when the user scrolls near the bottom of the viewport. This method will fetch the next page of content from the Reddit API by informing our subRedditPage$ observable. Below is an example of the initial implementation of our search-results component.

import {
  CdkVirtualScrollViewport,
  ScrollingModule,
} from '@angular/cdk/scrolling'

@Component({
  selector: 'app-search-results',
  standalone: true,
  changeDetection: ChangeDetectionStrategy.OnPush,
  imports: [CommonModule, ScrollingModule],
  schemas: [CUSTOM_ELEMENTS_SCHEMA],
  templateUrl: './search-results.component.html',
})
export class SearchResultsComponent {
  @ViewChild(CdkVirtualScrollViewport)
  public viewPort?: CdkVirtualScrollViewport

  /**
   * Observable used to display post content from Reddit.
   */
  protected readonly query$: Observable<IRedditQuery>

  /**
   * The size of the item.
   */
  public itemSize = 1264

  /**
   * Subscribes to the query observable.
   */
  public constructor(
    private readonly redditService: RedditService
  ) {
    this.query$ = this.redditService.getQuery()
  }

  /**
   * We'll implement this next!
   */
  public onScroll(nextPage?: string): void {}
}

In the template, we'll subscribe to query$ using the async pipe. One thing to note about Virtual Scrollers is that they become vastly more complicated if your content is not all equal heights. If your content is dynamic heights, or you don't know the sizes ahead of time, it can create performance implications, as recalculating can be expensive. In my example, every item is the same height.

<ng-container *ngIf="{query: query$ | async} as data">
  <ul *ngIf="data.query">
    <cdk-virtual-scroll-viewport 
      scrollWindow 
      [itemSize]="itemSize"
      (scrolledIndexChange)="onScroll(data.query.nextPage)">
      <li *cdkVirtualFor="let result of data.query.results" [height]="itemSize">
        <app-media [content]="result" [size]="itemSize"></app-media>
      </li>
    </cdk-virtual-scroll-viewport>
  </ul>
</ng-container>

Finally, we'll set up a method that will be called when the user scrolls near the bottom of the Virtual Scroller to fetch more content; in the prior example, this is leveraging scrollIndexChanged on cdk-virtual-scroll-viewport. This method accepts the following page ID as a parameter, which we set earlier as a property of the query$ stream, and emits to the subRedditPage$ observable. Once this is emitted, the service will fetch the next page of content from the Reddit API
and automatically update our list via the query$ observable.

  public onScroll(nextPage?: string): void {
    if (this.viewPort && nextPage) {
      const end = this.viewPort.getRenderedRange().end
      const total = this.viewPort.getDataLength()

      // If we're close to the bottom, fetch the next page.
      if (end >= total - SearchResultsComponent.FETCH_MINIMUM) {
        this.redditService.setSubRedditPage(nextPage)
      }
    }
  }

We'll also need to wire up other application parts, such as the search bar and the tab controls. Below is a small example of how I did this, it's pretty straightforward as it's just a form that emits the subRedditName property to the setSubRedditName method on the service.

<form (submit)="onSubmit()">
  <input type="text" [(ngModel)]="subRedditName" />
  <button type="submit">Search</button>
</form>

@Component({
  selector: 'app-search',
  templateUrl: './search.component.html',
  changeDetection: ChangeDetectionStrategy.OnPush,
  imports: [CommonModule, ReactiveFormsModule]
})
export class SearchComponent {
  /**
   * An observable containing the selected sub reddit name.
   * Used to push the current Reddit page back to the input placeholder.
   */
  public readonly subRedditName$: Observable<string>

  /**
   * @inheritdoc
   * @param formBuilder Injected form builder from Angular.
   * @param redditService Injected Reddit service.
   */
  public constructor(
    private readonly formBuilder: FormBuilder,
    private readonly redditService: RedditService
  ) {
    this.subRedditName$ = this.redditService.getSubRedditName()
  }

  /**
   * Contains all of the search form data points.
   */
  public searchForm = this.formBuilder.group({
    term: ''
  })

  /**
   * Handles submission of the search field.
   */
  public onSubmit(event: Event): void {
    if (this.searchForm.value.term) {
      this.redditService.setSubRedditName(this.searchForm.value.term.trim())
    }
  }
}

Conclusion

With all this rigged up, you'll have a virtually infinite scroller! Give it a try here. The Reddit API has a rate limit, so you might hit it quickly if you're testing this out. If you do, you can always try again later. I've also done a lot of additional work to mine, so please refer to the GitHub repository if you'd like to learn how to do the same.

Improving Code Quality with Linting

Jives — Fri, 11 Oct 2024 13:56:30 +0000

Whenever I start a new project, one of the first things I do is put in place a code linter. For the uninitiated, linters analyze your project and call out potential issues. They can provide guidance on everything from how much spacing is used between lines to specific implementation details, such as restricting the usage of certain patterns and habits. You can take these tools one step further by making them part of your CICD workflow, so your build fails if it detects non-compliant code.

To many, this may seem like a hassle, but depending on the scale of the project and the number of people working on it, using these tools is a way to standardize shared best practices and opinions across a whole team. After all, everyone is opinionated when it comes to writing code. You can take two completely different code bases written in the same language, and neither would look the same. In JavaScript, there are multiple ways to write the same thing. There are various ways of writing loops, defining functions, and even variables. As more people work on the same code base, their opinions come with them, and without a way to standardize, you'll soon end up in a hellhole of pull requests where people constantly leave unproductive "/nitpick" comments for basic things.

Linting and Formatting JavaScript

Setting up these types of tools is typically straightforward; you'll install a package, often from a registry, and then run something either on the command line or directly within your IDE with the help of a plugin.

One prevalent linting option for JavaScript is ESLint. ESLint is based on a shared configuration file you provide in your repository. Let's look at a relatively simple example of a configuration that inherits a series of grouped recommended rules for best practices. The community drives these recommended rules and even provides a mechanism for auto-fixing some of them with the –-fix flag.

import js from '@eslint/js';
import globals from 'globals';

export default [
  js.configs.recommended,
  {
    languageOptions: {
      ecmaVersion: 12,
      globals: {
        ...globals.browser,
      },
    },
  }
];

In addition to using the recommended rules, I also like to expand on them by adding several optional, more opinionated rules. For example, I'm not too fond of functions with many parameters as I've found that in the past, they can cause problems and generally become hard to follow, so in most of the codebases I work on, I enforce this using the max-params rule. I also like to ensure that my code is formatted a certain way, so I use the Prettier plugin to ensure that everything matches my Prettier config file, preventing discrepancies around commas and spacing.

import js from '@eslint/js';
import eslintPluginPrettierRecommended from 'eslint-plugin-prettier/recommended';
import globals from 'globals';

export default [
  js.configs.recommended,
  eslintPluginPrettierRecommended,
  {
    languageOptions: {
      ecmaVersion: 12,
      globals: {
        ...globals.browser,
      },
    },
  },
  {
    rules: {
      'max-params': ['error', 3],
      'no-unused-vars': 'error',
    },
  },
];

With this configuration, the following function will flag an error directly in my IDE or when I run ESLint via the command line, as it does not adhere to my max-param restrictions or the prettier configuration. If I were to run the linter in my CICD workflow, it would cause the build to fail, preventing me from merging it upstream, which is crucial if we want to ensure our shared branches are always in a good state.

const fetchData = async (endpoint, token, headers, params) => {
  try {
          const response = await fetch(endpoint, {
      headers: Object.assign({
        Authorization: `Bearer ${token}`
      }, headers),
      params
    });

const data = await response.json();


const newData = {
      ...data,
    additionalProperty: 'newValue',
    };

                return newData;
  } catch (error) {
    console.error('Error fetching data:', error);
  }
};

fetchData('https://api.example.com', 'token', { 'Content-Type': 'application/json' }, { page: 1 });

/Users/jives/fetch.js
   1:60  error  Async arrow function has too many parameters (4). Maximum allowed is 3                                                                                                                                                                  max-params
   2:3   error  Delete `··`                                                                                                                                                                                                                             prettier/prettier
   2:11  error  'cat' is assigned a value but never used                                                                                                                                                                                                no-unused-vars
   3:3   error  Delete `··`                                                                                                                                                                                                                             prettier/prettier
   4:1   error  Delete `········`                                                                                                                                                                                                                       prettier/prettier
   5:1   error  Replace `········headers:·Object.assign(` with `······headers:·Object.assign(⏎········`                                                                                                                                                 prettier/prettier
   6:43  error  Insert `,`                                                                                                                                                                                                                              prettier/prettier
   7:11  error  Replace `·headers)` with `⏎········headers`                                                                                                                                                                                             prettier/prettier
   8:7   error  Replace `··params` with `),⏎······params,`                                                                                                                                                                                              prettier/prettier
   9:1   error  Replace `······` with `····`                                                                                                                                                                                                            prettier/prettier
  10:1   error  Replace `······⏎` with `⏎··`                                                                                                                                                                                                            prettier/prettier
  12:1   error  Delete `··`                                                                                                                                                                                                                             prettier/prettier
  13:5   error  Delete `··⏎······`                                                                                                                                                                                                                      prettier/prettier
  15:7   error  Replace `········additionalProperty:·'newValue'` with `additionalProperty:·'newValue',`                                                                                                                                                 prettier/prettier
  16:1   error  Replace `······` with `····`                                                                                                                                                                                                            prettier/prettier
  17:1   error  Delete `··`                                                                                                                                                                                                                             prettier/prettier
  18:5   error  Delete `··············`                                                                                                                                                                                                                 prettier/prettier
  19:1   error  Replace `····` with `··`                                                                                                                                                                                                                prettier/prettier
  20:1   error  Delete `··`                                                                                                                                                                                                                             prettier/prettier
  21:3   error  Delete `··`                                                                                                                                                                                                                             prettier/prettier
  22:1   error  Delete `··`                                                                                                                                                                                                                             prettier/prettier
  23:1   error  Delete `··`                                                                                                                                                                                                                             prettier/prettier
  24:1   error  Replace `··fetchData('https://api.example.com',·'token',·{·'Content-Type':·'application/json'·},·{·page:·1·});` with `fetchData(⏎··'https://api.example.com',⏎··'token',⏎··{·'Content-Type':·'application/json'·},⏎··{·page:·1·},⏎);⏎`  prettier/prettier

✖ 23 problems (23 errors, 0 warnings)

If I resolve these issues, I no longer get an error, and the build will pass.

const fetchData = async ({ endpoint, token, headers, params }) => {
  try {
    const response = await fetch(endpoint, {
      headers: {
        Authorization: `Bearer ${token}`,
        ...headers,
      },
      params,
    });

    const data = await response.json();

    const newData = {
      ...data,
      additionalProperty: 'newValue',
    };

    return newData;
  } catch (error) {
    console.error('Error fetching data:', error);
  }
};

fetchData({
  endpoint: 'https://api.example.com',
  token: 'token',
  headers: { 'Content-Type': 'application/json' },
  params: { page: 1 },
});

Linters can also be a great way to reinforce good habits. For example, having a linting rule in your project for no unused variables can be a great way to teach the practice of not leaving unused references in code. As a maintainer, it improves your quality of life, and it's one less thing you'll need to consider during the pull request process. You can even use a linter to enforce that any types aren't used in TypeScript and other harmful practices that can cause bugs in your code.

Over time, your configuration file will evolve as you form best practices and needs amongst your team; you may decide to add or even remove unnecessary rules. The ultimate goal is more approachable code and less wasted time—what's not to like?

You Can and Should Lint CSS

You can even lint your stylesheets if you're working with CSS. One of my favourite tools for that is Stylelint. Similar to ESLint, it's configuration-based and lets you define what rules you want to include, it also has a recommended configuration that you can extend from.

{
  "extends": "stylelint-config-standard"
}

For example, linting CSS can be beneficial in cases where you need to support legacy browsers. Downgrading JavaScript is pretty common, but it's not always as simple for CSS. Using a linter allows you to be honest with yourself by flagging problematic lines that won't work in older environments, ensuring your pages look as good as possible for everyone.

{
  "extends": "stylelint-config-recommended",
  "plugins": [
    "stylelint-no-unsupported-browser-features"
  ]
  "rules": {
    "plugin/no-unsupported-browser-features": [true, {
      "browsers": ["Chrome >= 66"]
    }]
  }
}

Using this Stylelint plugin, the following CSS would flag an error as you can't use flex-gap in older Chrome versions. These properties are commonplace in modern codebases and can be easily missed if you're not testing older browsers. You can catch these issues with a linter before they become a problem.

.container {
  align-items: center;
  display: flex;
  gap: 10px;
  justify-content: center;
}

[js] src/styles.css
[js]    4:1  ✖  Unexpected browser feature "flexbox-gap" is not supported by Chrome 66,67,68,69,70,71,72,73,74,75,76,77,78,79,80,81,83  plugin/no-unsupported-browser-features

CSS linting can also be leveraged to ensure that you stick to a single unit of measurement for things like font sizes and even enforce the usage of CSS variables for certain property types, like colours and padding. These rules go a long way to providing consistency, especially when you may have multiple views or components.

Lint Early, Lint Often

Creating a baseline set of standards around linting at the start of a project is much easier. Adapting code as you write is much more straightforward than retrofitting an existing project. If you're starting a new project and already have another application that uses a linter, add the same ruleset to your new one and adapt it as you go along. Just because it's harder to adapt a linter to something already established doesn't make it any less worth it, though; it's just more of a time sink.

Most linters allow you to mark a rule as a warning or an error; warnings inform you of the problem when the linter is run, whereas an error will break your build pipeline, preventing it from going any further. I typically avoid setting any rules as a warning unless I am actively migrating code to where I can turn it on as an error. My process is usually:

Determine what rules should be enabled, discuss with your team if you're not working solo.
Enable the rule as a warning.
Fix the code that is flagging the warning.
Enable the rule as an error once all the warnings are resolved.
Avoid lint-ignore comments unless absolutely necessary.

I've made the mistake of doing large refactors to turn on linting rules and broken things. Play it safe and slowly make changes over time to avoid unnecessary headaches.

Closing Notes

Linting is a great way to ensure that your codebase is consistent and that you're following best practices; many options are available for different languages and frameworks that you can find with a quick search. They can be a pain to set up for established projects, but the benefits far outweigh the initial setup time. It's also a great way to reinforce good habits and ensure your codebase is clean and maintainable. If you're not already using a linter, I highly recommend you start. It's a small change that can positively impact your quality of life as a developer.

Figma Config 2024

Jives — Mon, 01 Jul 2024 19:05:37 +0000

This past week I attended the 2024 Figma Config conference. The conference was held in person in San Francisco, California, at the Moscone Convention Center and was a great opportunity to learn more about Figma and how other teams in the industry manage their design systems.

The ticket came with swag, including a Figma-branded notepad, bottle, pen, and a tote bag. A magazine was also included that discussed design trends and artificial intelligence.

You could line up and get a series of iron-on patches to apply to your tote bag to make it more personal; you could choose from three patches out of around 30, and where you placed them was entirely up to you.

The lines for activities at Config were closed during the keynotes. They were insanely long once they ended, so you would have to wait for a while if you hadn't been camping at the start before the keynote presentations concluded. In the future, they should leave the booths open during the keynote to prevent the lines from backing up. I get it —they want people to watch the keynotes, but it results in massive lines forming.

I came across extra patches, so I applied them to the back of my bag.

The swag bag also included a charm bracelet. All the different sponsorship booths and activities had additional charms you could add to your bracelet by visiting them. While my group tried to collect them all, many ran out quickly. We did our best, though!

A giant real-life Figjam board was set up in the lobby, which you could write on, allowing the opportunity for some shameless self-promotion.

There was also a user research booth with the option to record a video to send feedback to the Figma team. I had a lot to say about Figma Variables and some much-desired functionality when it comes to composite tokens and the ability to more easily get them out of Figma and into code.

Overall, the conference was nicely set up with a vibrant aesthetic and plenty of space to network. It certainly had personality.

Presentations and Learnings

Config was split into separate tracks, one of the tracks being a developer one on the first day and a design system track on the second, along with a keynote speech each day that unveiled all of the new features coming to Figma. I mostly split my time between these two tracks to absorb as much relevant knowledge as possible.

Plugins

On the first day, I particularly enjoyed the talks about how teams use the Figma Plugin API to automate mundane tasks and to add functionality to the software that otherwise doesn't exist. There was a great talk from Discord, who discussed how they have built a plugin manager called Spellbook; they use this as a single port of entry to continue providing new functionality to their designers without needing them to install multiple plugins. They showed examples of how they've built plugins to migrate iconography across an entire file to help speed up the adoption of their new icon sets. While a simple example, it got me thinking about how I could do more to make our lives easier with the help of Figma plugins, especially regarding more considerable sweeping changes.

Other talks about the Figma Plugin API included deep dives and live demos on how to use it and how easy it is to add additional functionality. After all, it's just a bit of JavaScript. This was the most inspiring of all the talk segments for me because it made me want to go out and build a plugin to learn how they are put together. It was good timing, too, with a holiday weekend rapidly approaching in the States!

Design Systems

I was worried that some design system talks would be too high level without showing actual examples of the problems they solved. I was pleasantly surprised, though, that there was a good amount of substance in the talks I attended. One that stood out in particular was a talk from Atlassian, which discussed how they improved the adoption of their system. They used practical examples around how they built ESLint rules, scorecards, and more aggressive delivery methods to help speed up the overall process of getting teams onboarded faster. The biggest takeaway from that talk was that not all adoption is good adoption, and helping guide others through education, tooling, and relationship building helped with the overall goal of getting adoption rates higher across their organisation using the intended patterns.

Another talk I enjoyed was from Alaska Airlines about how they've utilised their design system to power extra large displays in the airports they service with the help of tokens. The examples were tangible, and I even saw some of the displays in action on my way out of San Francisco airport.

Another standout talk for me was from GitHub, which discussed challenges with its design system, Primer. They went into detail about how organisational changes have altered the course of its development and how they've had to adjust to the needs of the business over time to adapt and grow. As an engineering lead, I really resonated with this talk.

Overall, the design system track helped me realise that some challenges are universally shared. Many organisations are trying to solve similar problems, and this paints a clear picture that design systems aren't this magical promised land but instead an opportunity to strengthen how teams work together if done correctly. I feel equally validated, assured, and inspired. I have left with questions, reflections and a sense of excitement.

Closing Notes

Overall, I had such a blast at Figma Config. It has been a while since I've been able to attend an in-person conference, and it was great to meet so many other people in the industry working on similar things. A big thank you to the Figma team for putting on such a great event, and a big thank you to my team for allowing me to attend. Check out the replays of all the talks online if you did not participate in person.

This was also my first time in downtown San Francisco, and I had the opportunity to do a bit of sightseeing while I was there too. However, I think the most standout part was these crazy self-driving cars from Waymo. I saw a concept version of these back at Google IO in 2018, and it's wild to be driven around by one. The future is truly here.

Half-Life Dedicated Server With Docker

Jives — Mon, 24 Jun 2024 13:03:31 +0000

I used to play a lot of Half-Life back in the day. I remember spending hours on all the mods available, such as Counter-Strike and Day of Defeat, and I even ran a few servers for me and my friends to play together. I played with all the various custom maps and mods available back then and remember having a blast doing so. I recently decided to revisit the game and wondered what it would take to set up a server with modern techniques using the Half-Life Dedicated Server client and Docker.

If you're unfamiliar with Docker, it's a tool that lets you run applications in isolated environments, known as containers. These containers ensure consistency and portability by containing all the dependencies and configurations needed to run an application. As a result, you can run the container on any machine with Docker installed and be confident that the application will run consistently, regardless of who runs it or where it's run, so long as the system architecture has support. When it comes to building a dedicated server with Docker, it is a great option, as all it takes to set one up is a series of terminal commands and a basic knowledge of how Half-Life organizes its game directories.

The general process of setting up a dedicated server includes:

Creating a Steam user on the host machine and installing dependencies.
Installing SteamCMD, a terminal utility provided by Valve for installing content from Steam.
Downloading the game files and starting the server.

You can find further documentation and explanations for all the concepts in this article on either the Valve Developer Wiki or the Docker documentation site.

For this project, I had a couple of high-level goals in mind that I wanted to achieve:

The server should be able to support all the classic Valve games, such as Half-Life Deathmatch, Counter-Strike, Team Fortress Classic, etc.
You should be able to install custom server plugins, configurations and maps.
You should be able to play custom mods other than the officially supported ones.

Building the Dockerfile

To start building a container, you must first create a file named Dockerfile, which contains scripts that will run as the container is building. These scripts help set up the structure of the host machine by creating necessary users, giving them permissions, and downloading all required files. You're essentially running a series of terminal commands in sequence, just like you would if you set this up on your system.

In the following example, we extend from a pre-built Ubuntu image, install some known dependencies, add our Steam user account on the system, and then switch to the working directory located at /opt/steam.

FROM ubuntu:18.04

ARG GAME=valve
ENV GAME ${GAME}

RUN dpkg --add-architecture i386 && \
    apt-get update && \
    apt-get install -y --no-install-recommends curl rsync file libc6:i386 lib32stdc++6 ca-certificates  && \
    rm -rf /var/lib/apt/lists/*

RUN groupadd -r steam && \
    useradd -r -g steam -m -d /opt/steam steam

USER steam
WORKDIR /opt/steam

Next, we'll install and invoke SteamCMD, a command-line version of the Steam client used to install content distributed through Steam Pipe. We'll use this to install the dedicated server client for Half-Life.

COPY ./hlds.txt /opt/steam
RUN sed -i "s/\$GAME/${GAME}/g" /opt/steam/hlds.txt

RUN curl -v -sL media.steampowered.com/client/installer/steamcmd_linux.tar.gz | tar xzvf - && \
    file /opt/steam/linux32/steamcmd && \
    ./steamcmd.sh +runscript /opt/steam/hlds.txt

Some things are worth mentioning, particularly the arguments passed to steamcmd.sh. We call +runscript hlds.txt, which points to a text file that batches a series of commands for the Steam client. Here, we log in to Steam anonymously, request the files for title ID 90 (the Steam title ID for the Half-Life Dedicated Server client), and then validate its contents. We do this multiple times as there's a known bug with SteamCMD where it will always fail on the first try for Half-Life mods.

Below, you'll find an example of what hlds.txt looks like.

@ShutdownOnFailedCommand 0
@NoPromptForPassword 1
force_install_dir ./hlds
login anonymous
app_set_config 90 mod $GAME
app_update 90 validate
app_update 90 validate
app_update 90 validate
quit

In Half-Life, every game based on it is treated as a mod, even if it's an official Valve title. Most of them originally started as such. Therefore, to download the correct files for our server, we must provide the mod's name to SteamCMD so it pulls the proper files. Before we request anything from SteamCMD, we replace any occurrence of $GAME in hlds.txt. This environment variable is also used throughout the script to ensure that we're moving specific files into the proper directories.

The value of $GAME can either be valve for Half-Life Deathmatch, cstrike for Counter-Strike, czero for Counter-Strike Condition Zero, dmc for Deatchmatch Classic, gearbox for Half-Life Opposing Force, ricochet for Ricochet, dod for Day of Deafeat, or tfc for Team Fortress Classic.

Starting the Server

At the end of Dockerfile we define an entrypoint.

WORKDIR /opt/steam/hlds

COPY --chown=steam:steam ./entrypoint.sh ./entrypoint.sh
RUN chmod +x ./entrypoint.sh

ENTRYPOINT ["./entrypoint.sh"]

The entry point script runs when we start the container. In this script, we prompt the dedicated server client to connect to Steam to allow players to join by calling ./hlds_run.

GAME=${GAME:-valve}

./hlds_run "-game $GAME $@"

You'll notice we're passing -game $GAME as an argument, as this tells the server client what mod directory to use. Half-Life splits all of its mods into subdirectories. These subdirectory names correspond with the same name passed to the +app_update command we used earlier. While you can only install officially supported things via SteamCMD, these folders can either be an official mod or a community-made mod, and as such, the -game argument needs to point to which mod folder within the leading Half-Life directory you want to run.

Additionally, we're passing $@ as an argument, the contents of this source from our docker-compose.yml file. This file acts as a manifest and tells Docker how to build and run our container, including any required ports to enable and additional parameters to pass to the entry point when its called. In this case, we're passing server startup arguments such as the max players and the map to start on.
In almost all cases the server requires a valid +map value to start properly, otherwise the server will start but not be joinable.

services:
  hlds:
    build:
      context: .
      args:
        - GAME=${GAME}
    ports:
      - "27015:27015/udp"
      - "27015:27015"
      - "26900:2690/udp"
    environment:
      - GAME=${GAME}
    command: +maxplayers 12 +log on +map cs_italy

With everything configured, you only need to run the following command to build the container image.

$ export GAME=cstrike
$ docker compose build

We can start our server with a single command if the image builds successfully.

$ docker compose up

With a bit of luck you should see the server start up and be joinable from the game client. If you're having trouble, always best to check the server logs that appear in the terminal output.

Supporting Custom Configs and Mods

Server configurations and plugins are typically installed by overwriting specific files within the mod directory. For example, to install a custom map rotation for Counter-Strike, you must add a mapcycle.txt alongside the rest of the files, for instance, hlds\cstrike\mapcycle.txt.

Custom mods are installed in a similar fashion and should be placed directly within our server's leading directory. For example, for a mod named "decay", the location would be hlds\decay. Server configurations for that mod would be placed in hlds\decay\server.cfg as an example.

To do this, we can utilize a Docker feature called volume mapping. This allows us to map a directory on the host machine to a directory inside the container when it starts. The benefit is that we can rapidly adjust our server without having to rebuild the image every time; all we need to do is stop the process and re-run docker compose up. We need to adjust our docker-compose.yml file for this to work. In this example, we're pushing the local ./config and ./mods directories within our folder to a directory called ./temp/config and ./temp/mods within the container.

services:
  hlds:
    build:
      context: .
      args:
        - GAME=${GAME}
    volumes:
      - "./config:/temp/config"
      - "./mods:/temp/mods"
    ports:
      - "27015:27015/udp"
      - "27015:27015"
      - "26900:2690/udp"
    environment:
      - GAME=${GAME}
    command: +maxplayers 12 +log on +map dy_accident1

Within the entrypoint.sh file, we copy the files from the temp directories into their respective places within the container; this will ensure that when the server starts, it has all the files it needs to run the respective mod or load any server configurations and plugins in the right place without altering the base image every time.

if [ -d /temp/mods ]
then
  rsync --chown=steam:steam /temp/mods/* /opt/steam/hlds
fi

if [ -d /temp/config ]
then
  rsync --chown=steam:steam /temp/config/* /opt/steam/hlds/$GAME
fi

echo -e "\e[32mStarting Half-Life Dedicated Server for $GAME...\e[0m"

./hlds_run "-game $GAME $@"

In all cases, you must ensure the $GAME environment variable is pointing to the name of the mod folder you want to play before you start the container, official or not as this ensures the server gets the correct -game parameter on startup.

$ export GAME=decay
$ docker compose build

Conclusion

Overall, this was a fun side, so hopefully, you found my explanation of it informative. This project forced me to learn the difference between ARM and x86-64 architecture, as many dependencies don't work with ARM based systems. Before trying anything, be sure you're using a compatible system, or you'll learn the hard way, as I did.

All the associated code is available on GitHub, including some pre-built images that remove a fair amount of boilerplate that this article covers that you can find on Dockerhub.
If you want to skip all of the above to run a Counter-Strike server, you only need to use docker compose up with the following docker-compose.yml file.

services:
  hlds:
    build: docker
    # 📣 Adjust the image value here with the desired game you want the server to use.
    image: jives/hlds:cstrike
    # 📣 Add all your custom configs/mods to a mods or config directory placed alongside the compose file.
    volumes:
      - "./config:/temp/config"
      - "./mods:/temp/mods"
    ports:
      - "27015:27015/udp"
      - "27015:27015"
      - "26900:2690/udp"
    environment:
      - GAME=${GAME}
    # 📣 Modify your server startup commands here.
    # 📣 Remember: Stating map is based on the game, and will likely be different between images.
    command: +maxplayers 12 +map cs_italy

If you try the project and have any feedback or questions, please let me know by leaving a note on the GitHub Discussions board.

Demystifying Web Components

Jives — Sat, 22 Jun 2024 14:24:28 +0000

Components are individual pieces of code which can be used in different contexts; they often represent a reusable piece of a design, such as a button or badge, and sometimes even as complex as more prominent elements like carousels and lightboxes. One of the many goals of a component is to bring consistency and cohesion, preventing multiple one-off implementations of the same thing across a codebase or several codebases. Components come in many flavours. For instance, they can be written in a framework like React, Angular, or just plain CSS. These are all great options, but these days, I've gravitated more towards Web Components.

But Why Web Components?

A Web Component is a reusable custom HTML element that encapsulates its functionality and styling; they are built using a set of web platform APIs that are part of the HTML and DOM specifications, including Custom Elements, Shadow DOM, and HTML Templates. Web components can be used in any JavaScript framework or library or with plain HTML and JavaScript, making them highly interoperable.

<daily-greeting></daily-greeting>

Consider Web Components in scenarios where you maintain multiple applications, especially if you have an active design system with a component library. Maintaining a component library written in a specific framework can often result in future applications being built in that same framework, as it's easier to integrate with your design system, even if that framework isn't the right choice for the project. Alternatively, suppose you're creating a new design system with existing legacy applications. In that case, the technology may already be all over the place, making Web Components an attractive choice.

Several companies have adopted Web Components already, most notably YouTube, GitHub, Adobe, and Alaska Airlines. All of these companies have been around for a long time and have a lot of applications they maintain.

There are more reasons besides interoperability, though. One of the big ones is the Shadow DOM. When used, components placed on a page become shielded from exterior factors, meaning external stylesheets and general document queries cannot mutate your components. This level of protection can be great for a design system, as an element will always look the same way no matter how and where you use it. If you need to support some degree of customization, you can leverage CSS variables as, by nature, they pierce the Shadow DOM. You can also use the part pseudo-element to allow external CSS to target specific things.

daily-greeting::part(message) {
  color: #333;
}

daily-greeting {
  --message-color: #333;
}

Additionally, the Shadow DOM provides the ability to build compositional components with the help of slots. Using these, you can provide an API for consumers to slot their elements into particular parts of a component. Slots are helpful as they allow for customization without being too restrictive. For example, suppose you want to support a header by providing it via a slot instead of an attribute. In that case, you can allow consumers to give a header tag relevant to where the component appears on their page to keep their DOM structure in a logical order. They also allow you to slot whole other components into one another, enabling you to build smaller atomic pieces that form more significant components and patterns when pieced together.

<section>
  <h1>My Page</h1>
  <p>Lorem ipsum dolor sit amet, consectetur adipiscing elit.</p>

  <daily-greeting>
    <h2 slot="header">Hello, world!</h2>
    <daily-icon slot="icon" icon="thumbs"><daily-icon>
  </daily-greeting>
</section>

Ultimately, adopting Web Components depends on your current and future scenarios. It's easy to become vendor-locked, and Web Components could be a way to avoid that.

Building a Web Component

So, how are these built? You'd be wrong to expect them to be overly complex and niche. Here's an example of a basic component that uses the connectedCallback lifecycle to show a greeting.

class DailyGreeting extends HTMLElement {
  connectedCallback() {
    this.render()
  }

  render() {
    let date = new Date()
    let currentHour = date.getHours()

    let greeting = ''
    if (currentHour < 12) {
      greeting = 'Good morning!'
    } else if (currentHour < 18) {
      greeting = 'Good afternoon!'
    } else {
      greeting = 'Good evening!'
    }

    this.shadowRoot.innerHTML = `
      <div part="message">
          ${greeting}
      </div>
        `
  }
}

window.customElements.define('daily-greeting', DailyGreeting)

We can easily support slots by adding a slot element. In the following example, I've added a default slot to a component which allows you to insert content to create a scrollable list. The following example includes more than slots; it covers several concepts, including attributes.

class ScrollSnapCarousel extends HTMLElement {
  static get observedAttributes() {
    return ['alignment']
  }

  constructor() {
    super()
    this.shadow = this.attachShadow({ mode: 'open' })
    this.alignment = 'start';

    this.scrollToNextPage = this.scrollToNextPage.bind(this)
    this.scrollToPreviousPage = this.scrollToPreviousPage.bind(this)
  }

  attributeChangedCallback(name, oldValue, newValue) {
    if (name === 'alignment') {
      this.alignment = newValue
    }
  }

  connectedCallback() {
    this.render()

    this.gallery = this.shadowRoot.querySelector('#paginated-gallery')
    this.galleryScroller = this.gallery.querySelector('.gallery-scroller')

    this.calculateGalleryItemSize()

    this.gallery
      .querySelector('button.next')
      .addEventListener('click', this.scrollToNextPage)

    this.gallery
      .querySelector('button.previous')
      .addEventListener('click', this.scrollToPreviousPage)

    window.addEventListener('resize', this.calculateGalleryItemSize)
  }

  disconnectedCallback() {
    window.removeEventListener('resize', this.calculateGalleryItemSize)
  }

  calculateGalleryItemSize() {
    const slotElement = this.galleryScroller.querySelector('slot')
    const nodes = slotElement.assignedNodes({ flatten: true })
    const firstSlottedElement = nodes.find(
      (node) => node.nodeType === Node.ELEMENT_NODE,
    )
    this.galleryItemSize = firstSlottedElement.clientWidth
  }

  scrollToPreviousPage() {
    this.galleryScroller.scrollBy(-this.galleryItemSize, 0)
  }

  scrollToNextPage() {
    this.galleryScroller.scrollBy(this.galleryItemSize, 0)
  }

  render() {
    this.shadowRoot.innerHTML = `
      <style>
      </style>

      <div id="paginated-gallery" class="gallery">
          <button class="previous" aria-label="Previous"></button>
          <button class="next" aria-label="Next" ></button>
          <div class="gallery-scroller">
            <slot></slot>
          </div>
      </div>
      `
  }
}

window.customElements.define('scroll-snap-carousel', ScrollSnapCarousel)

You can project content into specific areas by giving the slot a name. For example, if we wanted to add some disclaimer text beneath the carousel, we could do so by adding another slot for it with the name disclaimer.

render() {
  this.shadowRoot.innerHTML = `
    <style>
    </style>

    <div id="paginated-gallery" class="gallery">
      <button class="previous" aria-label="Previous"></button>
      <button class="next" aria-label="Next" ></button>
      <div class="gallery-scroller">
        <slot></slot>
      </div>
    </div>
    <slot name="disclaimer"></slot>
      `
  }

With the custom element registered, all you'd need to do is place the following in the HTML to use the component.

<scroll-snap-carousel alignment="start">
  <iframe src="https://www.youtube.com/embed/3ZTvsUeQkOM?si=iNSnBcZRKWsMUB2e" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen></iframe>
  <iframe src="https://www.youtube.com/embed/7Dr5LW9xnSs?si=aLyux8R2QGk61XwU" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen></iframe>
  <iframe src="https://www.youtube.com/embed/31lbp1dolAI?si=B1SYEzLmlZ8QN3pG" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen></iframe>
  <iframe src="https://www.youtube.com/embed/onthvMAIpUI?si=XZK9y1OkfAhMJUFY" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen></iframe>
  <iframe src="https://www.youtube.com/embed/Ij-1kXYKD3c?si=ha_b0VuYevv-6q-V" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen></iframe>
  <iframe src="https://www.youtube.com/embed/RFdLLDmTTk8?si=1RVxxa3Hw-nL8ph8" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen></iframe>

  <span slot="disclaimer">Videos by <a href="">RayRay</a></span>
</scroll-snap-carousel>

This is what our component looks like. You can test it on Codepen, too, if you'd like to mess around with the API and get a more in-depth explanation of what all the methods do. If you have never encountered a Web Component before, especially one that utilizes the Shadow DOM, open up your browser debugger to inspect it!

The Shadow DOM Is Optional

You don't need to use the Shadow DOM; it's optional. Not using the Shadow DOM could be a good choice if you intend to provide smaller components with the expectation that others will apply additional styling or logic and don't want to offer part selectors or CSS variables for everything. However, removing the Shadow DOM also eliminates the ability to slot content, which is a significant loss and could make building specific components that rely on composition more challenging.

Using the previous example, I worked around the lack of slots by manipulating the tree with document.createDocumentFragment and appending child items in the correct spot after the component connects. It could be better, but it does work. As with anything, use your best judgment based on your needs to determine whether you should leverage the Shadow DOM. It can be more of a hindrance not to use it if you have a sound system for supporting variables as you lose the encapsulation benefits.

class ScrollSnapCarousel extends HTMLElement {
  static get observedAttributes() {
    return ['alignment']
  }

  constructor() {
    super()
    this.alignment = 'start'
    this.scrollToNextPage = this.scrollToNextPage.bind(this)
    this.scrollToPreviousPage = this.scrollToPreviousPage.bind(this)
    this.calculateGalleryItemSize = this.calculateGalleryItemSize.bind(this)
    this.ingestChildren = this.ingestChildren.bind(this)
  }

  attributeChangedCallback(name, oldValue, newValue) {
    if (name === 'alignment') {
      this.alignment = newValue
    }
  }


  connectedCallback() {
    this.ingestChildren()
    this.render()

    this.gallery = this.querySelector('#paginated-gallery')
    this.galleryScroller = this.gallery.querySelector('.gallery-scroller')
    this.galleryScroller.appendChild(this.fragment)

    this.gallery
      .querySelector('button.next')
      .addEventListener('click', this.scrollToNextPage)

    this.gallery
      .querySelector('button.previous')
      .addEventListener('click', this.scrollToPreviousPage)

    this.calculateGalleryItemSize()
    window.addEventListener('resize', this.calculateGalleryItemSize)
  }


  disconnectedCallback() {
    window.removeEventListener('resize', this.calculateGalleryItemSize)
  }


  ingestChildren() {
    this.fragment = document.createDocumentFragment()

    Array.from(this.children).forEach((child) => {
      this.fragment.appendChild(child)
    })
  }

  calculateGalleryItemSize() {
    const nodes = Array.from(this.galleryScroller.children)
    const firstElement = nodes.find(
      (node) => node.nodeType === Node.ELEMENT_NODE,
    )
    this.galleryItemSize = firstElement.clientWidth
  }


  scrollToPreviousPage() {
    this.galleryScroller.scrollBy(-this.galleryItemSize, 0)
  }


  scrollToNextPage() {
    this.galleryScroller.scrollBy(this.galleryItemSize, 0)
  }


  render() {
    this.innerHTML = `
        <style>
        </style>

        <div id="paginated-gallery" class="gallery">
            <div class="gallery-scroller"></div>
            <button class="previous" aria-label="Previous"></button>
            <button class="next" aria-label="Next" ></button>
        </div>
          `
  }
}

window.customElements.define('scroll-snap-carousel', ScrollSnapCarousel)

If you want to try it out, the example above is available on Codepen. Like the previous example, open your browser debugger to see how it's constructed, and you'll notice the lack of shadow root in the component tree.

A very active thread on GitHub discusses the concept of a Shadow DOM that supports a stylable root. Still, it's in the discussion phase, so it will be long before this manifests into something usable.

Consider a Framework

Consider adopting something like Lit or Stencil to build Web Components. These frameworks provide standard utilities for working with Web Components and handle everyday tasks such as change detection, server-side rendering, localization, etc. I've personally worked with Lit and find it helpful for preventing common mistakes and pitfalls. Additionally, they provide a series of best practices for authoring components, which I often refer to. Something Stencil provides which is unique is a polyfill for slot for usage in non-Shadow DOM components, which may be attractive to some.

Here's an example of a basic Lit element with TypeScript support. It's similar to my previous examples and ultimately results in something similar through class extensions.

import {html, css, LitElement} from 'lit';
import {customElement, property} from 'lit/decorators.js';

@customElement('simple-greeting')
export class SimpleGreeting extends LitElement {
  static styles = css`p { color: blue }`;

  @property()
  name = 'Somebody';

  render() {
    return html`<p>Hello, ${this.name}!</p>`;
  }
}

The philosophy of these frameworks is similar to that of any other: they help you move faster. With these, you get all the benefits of using Web Components without writing lots of boilerplates every time you write a component.

General Tips

I've learned a lot after working with Web Components for a while. Here's a general list of things I've picked up.

Be careful with inheritance in cases where a component doesn't define its own DOM tree and instead renders a pre-configured version of another. If you have components that follow this pattern, you run the risk of exploding your applications with additional DOM nodes, especially if you forward slots. Consider using a class extension instead, or reconsider if a new component is necessary.
Document your components. Tooling is available to analyze JSDoc comments and produce artefacts from the output, such as README files. An excellent add-on for Storybook will take that output and automatically generate controls for your component API.
Use a linter and write unit tests. Web Components have a habit of silencing errors, which can be frustrating to track down. The more tooling you add around them, the better your developer experience. Lit for example provides a linter that can catch common mistakes.
Keep tabs on the industry. Web components are still evolving, and some things are constantly being discussed or considered. Get involved in the conversation!

You'll make mistakes, especially if it's your first time working with Web Components. While they are similar to working with other frameworks, they have their unique quirks that aren't always obvious at first.

Conclusion

Overall, I really enjoy working with Web Components. While some have given them a bad rap, the technology is progressing in a favourable way, and many teams are starting to seriously consider them. They are the backbone to the design system I work on and have been a great way to ensure consistency across our applications.

Syncing Figma Variables and StyleDictionary with GitHub Actions

Jives — Thu, 03 Aug 2023 11:28:40 +0000

Figma recently announced its new Variables product, allowing you to define and manage your design tokens directly within Figma. I have been experimenting with Figma Variables for a few weeks and am reasonably impressed with how it works. In this article, I'll share how I've been using Figma Variables to support my design projects and how I've been syncing them with my codebase with GitHub Actions and StyleDictionary, utilising a dev preview of the Figma API. For this article, I’ll focus primarily on syncing these variables one way from Figma to GitHub, making Figma the source of truth for all my design tokens.

Required Tooling

Before we start, I'd like to quickly review the tools I'll use to sync my variables from Figma:

Figma - Naturally, we'll need Figma. Sadly, you'll need the enterprise plan to access the API used in this article, as there are additional scopes required that the free program does not offer. Please change this Figma... 🙏

StyleDictionary - StyleDictionary is a tool that allows you to transform your design tokens into various formats. We'll use this to convert the variables pulled from Figma to be used across different platforms. I'll use a fresh installation of StyleDictionary version 3.8.0 to keep things simple.

GitHub Actions - To sync the variables from Figma to GitHub, we'll use GitHub Actions to run automations. We can use this to run a workflow on a schedule that will automatically update our variables daily. If you don't have access to Actions, you can use any other CI/CD tool that supports running a script on a schedule.

Connecting to the API

The first thing we'll need to do is connect to the Figma Rest API. We'll need to create a new personal access token to do this with the 1file_variables:read1 scope. You can accomplish this by visiting your account settings in Figma and clicking the "Personal Access Tokens" tab. From here, you'll want to click the "Create a new personal access token" button and give it a name. Ensure you note this value, as we'll be referencing it later.

Our variables waiting to be pulled from the API.

With our personal access token in hand, we can make the following API request to get a list of tokens back from the Figma API. In the following example, you'll want to replace the fileKey value with the file id from which you'd like to pull variables. You can find this value by going to the file in question and copying the id from the URL.

curl -H 'X-FIGMA-TOKEN: <personal access token>' 'https://api.figma.com/v1/files/:file_key/variables/local'

Below, you'll see what you get back from the Figma API. I've removed some of the values for brevity.

{
  "meta": {
    "variables": {
      "VariableID:2:41": {
        "id": "VariableID:2:41",
        "name": "Primary",
        "variableCollectionId": "VariableCollectionId:2:15",
        "resolvedType": "COLOR",
        "valuesByMode": {
          "2:0": "00A4EF",
          "2:1": "107C10"
        },
        "remote": false
      },
      "VariableID:2:40": {
        "id": "VariableID:2:40",
        "name": "Secondary",
        "valuesByMode": {
          "2:0": "F25022",
          "2:1": "3A3A3A"
        },
        "variableCollectionId": "VariableCollectionId:2:15",
        "resolvedType": "COLOR"
      },
      "VariableID:2:39": {
        "id": "VariableID:2:41",
        "name": "Tertiary",
        "valuesByMode": {
          "2:0": "7FBA00"
        },
        "variableCollectionId": "VariableCollectionId:2:15",
        "resolvedType": "COLOR"
      }
    },

    "variableCollections": {
      "VariableCollectionId:2:15": {
        "id": "VariableCollectionId:2:15",
        "name": "Brand Colours",
        "modes": [
          {
            "id": "2:0",
            "name": "Microsoft"
          },
          {
            "id": "2:1",
            "name": "Xbox"
          }
        ],
        "defaultModeId": "2:0",
        "remote": false
      }
    }
  }
}

If we examine the payload closer, there are a few things to note here. Firstly, we have a grouping called variableCollections, which, as you guessed, contains our variable collections along with any associated modes. Modes represent different brands or themes, such as light or dark, within your design system. In this example, we have two modes, one for Microsoft and one for Xbox. We can see that the default mode is set to Microsoft as its id points to 2:0.

For this example, we'll implement fallback behaviour, where if a variable is not defined for a given mode, we'll fall back to the default mode. This behaviour is helpful when a variable is shared across all modes, such as a primary or secondary colour. This may not be desired, however, depending on your use case, so adjust accordingly. You may want to instead throw an error if a variable is not defined for a given mode, or leave the variable undefined and provide a reasonable default in your applications.

GitHub Actions Workflow

Using GitHub Actions, we'll request this endpoint on a schedule and save its contents within our GitHub repository, where our StyleDictionary instance lives. If you're unfamiliar with GitHub Actions, check out my previous article, where I talk in detail about some of the actions we'll use in this example.

The gist of what's happening here is that we request the Figma API and then save the raw response to a file within the repository, in a file called figma.json, within the data directory. Later, we'll reference this file in a scheduled job to transform and build our design tokens for usage in their projects.

name: Figma Variables Sync
on:
  schedule:
    - cron: 10 15 * * 0-6
jobs:
  refresh-feed:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout 🛎️
        uses: actions/checkout@v2
        with:
          persist-credentials: false

      - name: Fetch Figma API Data 📦
        uses: JamesIves/fetch-api-data-action@releases/v2
        with:
          endpoint: https://api.figma.com/v1/files/${{ secrets.FILE_ID }}/variables/local
          configuration: '{ "method": "GET", "headers": {"X-FIGMA-TOKEN": "${{ secrets.FIGMA_PAT }}"} }'
          save-name: figma

      - name: Deploy Workspace Changes 🚀
        uses: JamesIves/github-pages-deploy-action@releases/v4
        with:
          branch: main
          folder: fetch-api-data-action
          target-folder: data

Remember you need to save any secrets within your repositories' secrets menu. Refer to the GitHub documentation for details on how to do this.

Configuring Style Dictionary

At this stage in our workflow, we've fetched the raw response from the Figma API, so it's available within our codebase. However, we must still transform it into a format that StyleDictionary understands. Where this transformation takes place is up to you–this could happen in your actions workflow within a follow-up step, or you could transform it right within StyleDictionary. It's totally up to you. Doing whatever works on your existing workflows and patterns would be best.

Transforming the Data

For this example, we'll take care of this within StyleDictionary. Create a transform.js file at the project's root and run it before StyleDictionary's build scripts execute. This transformer will standardise the format of our variables, removing any unnecessary data and flattening the structure. We'll also create a file for each mode and then a file for each resolvedType within that mode. For instance, if our Figma variable set included strings and colours, it will create a tokens/brands/{brand}/color.json and tokens/brands/{brand}/string.json file for each mode.

const inputData = require("./data/figma.json");
const outputDirectory = "./tokens/brands";

const createDirectory = async (dirPath) => {
  try {
    await fs.mkdir(dirPath, { recursive: true })
  } catch (err) {
    if (err.code !== 'EEXIST') throw err
  }
}

const transformFigmaVariables = async () => {
  const transformedData = {}

  /**
   * Loop through each variable and mode and create a new object.
   */
  Object.values(inputData.meta.variables).forEach((variable) => {
    const { name, valuesByMode, variableCollectionId, resolvedType } = variable

    const { defaultModeId } =
      inputData.meta.variableCollections[variableCollectionId]

    const defaultModeValue = valuesByMode && valuesByMode[defaultModeId]

    /**
     * Group variables by resolved type.
     */
    Object.values(
      inputData.meta.variableCollections[variableCollectionId].modes,
    ).forEach((mode) => {
      const { id: modeId, name: modeName } = mode
      const modeValue = valuesByMode && valuesByMode[modeId]

      if (!transformedData[modeName]) {
        transformedData[modeName] = {}
      }

      if (!transformedData[modeName][resolvedType]) {
        transformedData[modeName][resolvedType] = {}
      }

      /**
       * If a variable is not defined for a given mode, we'll fall back to the default mode.
       */
      transformedData[modeName][resolvedType][name.toLowerCase()] = {
        value: modeValue || defaultModeValue,
      }
    })
  })

  /**
   * Generates files for each mode and type.
   */
  await Promise.all(
    Object.entries(transformedData).map(async ([modeName, modeData]) => {
      const sanitizedModeName = modeName.toLowerCase().replace(/\s+/g, '-')
      const modeDirectory = path.join(outputDirectory, sanitizedModeName)

      await createDirectory(modeDirectory)

      await Promise.all(
        Object.entries(modeData).map(async ([resolvedType, data]) => {
          const resolvedTypeTitle = resolvedType.toLowerCase()
          const outputFilePath = path.join(
            modeDirectory,
            `${resolvedTypeTitle}.json`,
          )

          await fs.writeFile(
            outputFilePath,
            JSON.stringify({
              [resolvedTypeTitle]: { ...data },
            }),
          )
        }),
      )
    }),
  )
}

By all means, this script isn't full-proof, but it gets the job done. Given our payload example above, it created two sets of variables–one located within tokens/brands/microsoft/color.json, which looks like the following:

{
  "color": {
    "primary": {
      "value": "00A4EF"
    },
    "secondary": {
      "value": "F25022"
    },
    "tertiary": {
      "value": "7FBA00"
    }
  }
}

And another within tokens/brands/xbox/color.json. In this example, as Xbox doesn't have a tertiary colour, it falls back to the tertiary colour of the default mode, which is the Microsoft brand. While the Figma UI may require you to have a value for each mode, it's not required when defining variables via the API, which is how you may get in this state.

{
  "color": {
    "primary": {
      "value": "107C10"
    },
    "secondary": {
      "value": "3A3A3A"
    },
    "tertiary": {
      "value": "7FBA00"
    }
  }
}

Defining the Platform

At this point, we need to define the platforms we want to make our variables available to by extending build.js that comes with StyleDictionary. I'll be compiling web/css for this example, but you can extend the config as much as you need. The real joy of StyleDictionary is that you can define platforms for as many formats as you want. For instance, if you maintain a website alongside a native mobile app, you can source your design tokens from the same place and compile them into the formats you need for both.

function getStyleDictionaryConfig(brand) {
  return {
    source: [`tokens/brands/${brand}/*.json`, 'tokens/globals/**/*.json'],
    platforms: {
      /**
       * Available platforms: https://amzn.github.io/style-dictionary/#/config?id=platform
       */
      web: {
        transformGroup: 'web',
        buildPath: `build/web/${brand}/`,
        files: [
          {
            destination: 'tokens.scss',
            format: 'scss/variables',
          },
        ],
      },
    },
  }
}

/**
 * Build the tokens for each brand.
 * {@see - Example based on https://github.com/amzn/style-dictionary/tree/main/examples/advanced/multi-brand-multi-platform}
 */
['microsoft', 'xbox'].map(function (brand) {
  ['web'].map(function (platform) {
    const StyleDictionary = StyleDictionaryPackage.extend(
      getStyleDictionaryConfig(brand),
    )

    StyleDictionary.buildPlatform(platform)
  })
})

Once the npm run build script has run, you should see all of the files you need.

:root {
  --color-primary: #00a4ef;
  --color-secondary: #f25022;
  --color-tertiary: #7fba00;
}

:root {
  --color-primary: #107c10;
  --color-secondary: #3a3a3a;
  --color-tertiary: #7fba00;
}

Publishing the Variables

Once you have StyleDictionary exporting everything you need, the last thing to do is publish it to your chosen registry. I like to do this every time the nightly job runs to sync the variables if there is a change. This way, I can be sure that the latest variables are always available to my team.

I have a dependent job that runs after the nightly sync that will publish the variables to a registry. Here's an example I put together using npm. You'll need to modify this based on the platform registry you're using.

name: Publish Variables
on:
  workflow_run:
    workflows: ["Figma Variables Sync"] # This must match the name of the workflow that syncs the variables
    types:
      - completed

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - uses: actions/setup-node@v3
        with:
          node-version: '18.x'
          registry-url: 'https://registry.npmjs.org'

      - name: Configure Git
        run: |
          git config --global user.name 'Automated publish'
          git config --global user.email '${{github.actor}}@users.noreply.github.com'

      - name: Build StyleDictionary and Publish
        if: ${{ github.event.workflow_run.conclusion == 'success' }} # Only run if the nightly sync was successful
        env:
          NODE_AUTH_TOKEN: ${{ secrets.NPM_PUBLISH_TOKEN }}
        run: |
          npm version patch
          git push && git push --tags

          npm ci
          npm run build

          cp package.json ./build && cd build

          npm publish

Now, my project just needs to install the published npm package and ingest the bundled CSS to switch between themes easily. With this configuration, if I update any of my variables in Figma, my front-end projects simply need to update their package version to get any changes populated automatically, keeping everything in sync with Figma. You could even get fancier with GitHub Actions here by configuring Dependabot to auto-merge any updates to the package and build on commit–but that's a topic for another day.

Conclusion

Hopefully, this helps you get started with the Figma Variables REST API. You may need to change some of the processes here depending on how you or your team works, but that’s the nature of the game when it comes to design systems. Remember that Figma Variables is still in beta, so much of this article is highly susceptible to change.

Additionally StyleDictionary can be useed for so much more, and I highly recommend you check out the StyleDictionary documentation to see what else it can do. I've only scratched the surface here, but it's a great tool to have in your arsenal when it comes to working with design systems.

Fostering Positive Change with Innovation Week

Jives — Mon, 24 Jul 2023 11:07:25 +0000

“Innovation Week” is a term used to describe a structured week-long event that brings together an entire team to work on new ideas and projects while providing an avenue for personal growth at the same time. It's a time to step away from day-to-day work and focus on something new and exciting. I was first introduced to Innovation Week during my time at United Income, and I thoroughly enjoyed it. It was a great way to get our teams involved and fostered collaboration on projects we would otherwise likely not have time for. Since moving roles, my new position has also adopted the same concept, and since then, its influence has been spreading to more and more teams within the company. Innovation Week is essentially a mini-hackathon with more structure. Let’s get into how it works.

How it works

During Innovation Week, team members self-organize into groups to work on projects of their creation and choosing. These groups can be as small as one to two people or as large as 10+, and each group member arbitrarily determines the roles within those groups.

Whenever I participate, I always like to try and work on something I only sometimes get to do in my daily work. For example, I'm a software engineer. Still, I also like UI design work, so I use Innovation Week to practice expanding my skill set and pursue something I’m interested in outside of coding. Others may use the time to practice product ownership by gathering requirements and documentation. - Jives

The projects can be anything- the only requirement is that it's tangentially related to the business or organisation I've had the pleasure of working on a fair number of projects during Innovation Week in my roles that have adopted it; for example, I worked on Slackbot Destroyer, put together a component library for United Income, and even collaborated on a project that provided our remote teams with an opportunity to get a virtual tour of our office using a Google Cardboard headset.

I worked on the office virtual reality tour with Melissa who learned how to write code for the project.

We produced the images using a pretty h̶a̶c̶k̶y̶ innovative camera rig.

While not all projects will have a long-lasting business impact (and that's OK), many do. As a team leader, your part in executing a successful Innovation Week is assessing those projects and helping to guide them to completion.

How to get started

The following steps outline how you can establish your own innovation week. These steps are flexible. Adapt them to whatever works best for your team. Every team is different, and what works for one may not work for another.

1. Set a date 📅

Make Innovation Week a regular event. My team does ours once a quarter. This gives enough time to plan and get excited about it. Having a place to write down ideas is also good so they can be revisited later. You could use a Trello board or a shared Google Doc for this to ensure it's accessible to everyone throughout the year. Keep ideas from previous Innovation Weeks in the same document, too, so they can be referenced or worked on later.

2. Pitch 🥎

Have everyone pitch their ideas to the rest of the participants. This is a great way to get people excited about the event and to get feedback on their ideas. It also provides an opportunity for people to recruit others for their projects. For example, if you're a designer who needs a developer, you can pitch your idea and find one. We often schedule a pitch meeting about a week or two before Innovation Week. This also allows for ordering any required hardware or software licenses that teams may need if the budget allows.

It's crucial that, as a leader, you take a step back during this process and allow your team to come up with their ideas independently, even if you don't think they'll work long-term. Your role here is to advise, help guide, and not dictate. If you're unsure about an idea, ask questions and provide feedback, but don't shoot it down. You can also help connect those without a project with teams who need them.

3. Innovate 💡

Once Innovation Week begins, it's time to get to work. This is the fun part!

The point of Innovation Week is to remove strict guidelines and processes and allow people to work on things they are passionate about. Ideally, the only meetings that should happen are those within the Innovation Week projects.

From Monday to Friday, everyone works on their projects. Encourage (or even require) everybody to stop their regularly scheduled work (except live issues) and focus on their innovation tasks only. Remove distractions - no scrum ceremonies, no project syncs, and no meetings—just innovation.

I also like to do a team event during Innovation Week, either an expensed lunch/breakfast or something similar to make an occasion out of the event.

4. Present and Celebrate 🎤 🎉

On the last day of innovation week, have everyone present their projects and celebrate their learnings. Remember - only some innovations will be successful in the traditional sense. But every innovation should have driven learning - what worked, what didn't, what was unexpected, and most importantly, what did we learn?

Extend the invite to people outside the team interested in seeing what you've all been working on; if you're small enough, invite the whole company. Inviting everyone is a great way to get feedback on your projects and show off everyone's hard work. It also provides an opportunity to get buy-in from stakeholders interested in seeing your projects through to completion.

Encourage questions and feedback from the audience, and provide a list of resources for people to learn more. I also like to include the project's next steps and the remaining work left before it can be considered "done".

5. Discuss 💬

As team leaders, your role is to discuss the Innovation Week demos and decide which projects should be continued and added to the roadmap and which should be put on hold. You'll rarely have the resources to continue all of the projects, so it's essential, to be honest with your team about which ones you think are worth pursuing. If you're unsure, ask for feedback from your team and other stakeholders. Ensure that everyone feels heard and that their work is valued.

Go beyond just the demos, too. Discuss new tools that the teams used or new ways of organising work that can improve the day-to-day. Remember, innovation week projects could change an existing process, such as a standup or retrospectives; these are all valid ways to innovate.

It may be that some projects need more time to develop, and revisiting them during the next Innovation Week may be the preferred approach.

Your goal as a team lead is to make sure something tangible comes out of each innovation sprint, no matter how small it may be. This will help demonstrate the ongoing value that innovation sprints bring and build support for this time to innovate across the organisation.

6. Repeat 🔁

Do it again and again, and keep innovating. Make it a regular occurrence. Ultimately everyone owns what they work on. Allowing everyone to reflect their passion and ideas into the product roadmap is a great way to keep people engaged and your team evolving.

Conclusion

Projects that have come from Innovation Week have gone on to become some of the most successful changes for the teams I’ve worked on. It's an event that I think brings teams together positively and helps promote exciting changes within a team or company at large. If I had my way, however, this is how I'd like to see teams operate all the time instead of it being just a week-long endeavour.

Hopefully, this article helps you to start your own Innovation Week, and if you do, I'd love to hear about it!