feat: add the NEW component "WeekRenderer" to render ISO week numbers

Author: khatastroffik

.storybook/utils.ts

@@ -1,3 +1,41 @@
+/**
+ * Removes the "key" attribute from the story component source code
+ * Note: the "key" attribute should be removed, since it is only used to allow dynamic rendering of the story.
+ * 
+ * @param code the original component code used to produce the story
+ * @returns the component code to be displayed in the story
+ */
 export const RemoveKeyAttribute = (code: string) => {
     return code.replace(/^.*key.*$\n/gm, "")
 }
+
+/**
+ * timeZoneSamples is used by the DateRenderer and the TimeRenderer stories
+ */
+const timeZoneSamples = { 
+    PacificNiue: ["Pacific/Niue", "-11"],
+    PacificGalapagos: ["Pacific/Galapagos", "-9"],
+    EuropeDublin: ["Europe/Dublin", "+0/+1"],
+    EuropeParis: ["Europe/Paris", "+1/+2"],
+    IndianMauritius: ["Indian/Mauritius", "+4"],
+    EtcGMTMinus8: ["Etc/GMT-8", "+8"],
+    PacificTongatapu: ["Pacific/Tongatapu", "+13"],
+}
+export const timeZoneLabels = Object.keys(timeZoneSamples).map((tz) => `${timeZoneSamples[tz][0]} (${timeZoneSamples[tz][1]})`);
+export const timeZoneOptions = Object.keys(timeZoneSamples).map((_, i)=> i);
+export const timeZoneMappings = Object.keys(timeZoneSamples).map((tz) => timeZoneSamples[tz][0]);
+
+/**
+ * numberingSystemSamples is used by the WeekRenderer story
+ */
+const numberingSystemSamples = {
+    arab: "Arabic-Indic digits",
+    brah: "Brahmi digits",
+    deva: "Devanagari digits",
+    hanidec: "Chinese number ideographs",
+    latn: "Latin digits",
+    tibt: "Tibetan digits"
+}
+export const numberingSystemLabels = Object.keys(numberingSystemSamples).map((tz) => numberingSystemSamples[tz] );
+export const numberingSystemOptions = Object.keys(numberingSystemSamples).map((_, i)=> i);
+export const numberingSystemMappings = Object.keys(numberingSystemSamples);

README.md

@@ -31,6 +31,7 @@ Please read the [CHANGELOG](./CHANGELOG.md) (all changes since the beginning) an
 - `DateRenderer` component ([Storybook → DateRenderer](https://khatastroffik.github.io/react-text-renderer-components/?path=/docs/components-daterenderer--daterenderer-documentation))
 - `TimeRenderer` component ([Storybook → TimeRenderer](https://khatastroffik.github.io/react-text-renderer-components/?path=/docs/components-timerenderer--timerenderer-documentation))
 - `DateTimeRenderer` component ([Storybook → DateTimeRenderer](https://khatastroffik.github.io/react-text-renderer-components/?path=/docs/components-datetimerenderer--datetimerenderer-documentation))
+- `WeekRenderer` component ([Storybook → WeekRenderer](https://khatastroffik.github.io/react-text-renderer-components/?path=/docs/components-weekrenderer--weekrenderer-documentation))
 
 more components to come... (see the ToDos below)
 
@@ -101,7 +102,7 @@ This design allows to avoid repetitions, reduce the size of the compiled code us
 
 ### Implement supplemental renderer components
 
-- ⬛ `WeekRenderer` component
+- ✅ `WeekRenderer` component
 - ⬛ `QuarterRenderer` component
 - ⬛ `TextRenderer` component (with text manipulation like UpperCase, LowerCase, Replace...)
 - ⬛ `CurrencyRenderer` component

src/components/WeekRenderer/WeekRenderer.mdx

@@ -0,0 +1,36 @@
+import { Primary, Canvas, Source, Meta, ArgTypes, Description, Controls } from '@storybook/blocks';
+import * as WeekRendererStories from './WeekRenderer.stories';
+
+<Meta of={WeekRendererStories} name="WeekRenderer Documentation"  />
+
+# WeekRenderer
+
+<Description of={WeekRendererStories} />
+
+### Preview
+
+<Primary />
+
+### Properties
+
+The text representation can be customized using the appropriates tag attributes i.e. component properties, as described below.
+
+<Controls of={WeekRendererStories.Playground} />
+{/* <ArgTypes of={WeekRendererStories} sort="requiredFirst" /> */}
+
+Notes:
+
+- The values and options used/available within the "Control" column are for demonstration purpose only.
+- Use the "Reset controls" button on the top right side of the table in order to restore the initial demo values and options. Alternatively, you could reload the page.
+
+### Usage
+
+<Source dark type={"jsx"} code={`
+import { WeekRenderer } from 'react-text-renderer-components';
+
+const Example = () => {
+    return <WeekRenderer value={new Date()} />
+}`
+} />
+
+Back to the [Github Repository](https://github.com/khatastroffik/react-text-renderer-components)

src/components/WeekRenderer/WeekRenderer.spec.tsx

@@ -0,0 +1,77 @@
+import React from "react";
+import { render } from '@testing-library/react';
+import { WeekRenderer, calcISOWeek, defaultWeekRendererFormatOptions } from "./WeekRenderer";
+
+const dateString = "2025-12-29T11:11:11.111Z";
+const dateValue = new Date(dateString);
+
+describe("WeekRenderer component", () => {
+
+    it("should render a week number of a date value to a pure 2-digits string", () => {
+        const r = render(<WeekRenderer value={dateValue} pure />);
+        const x = calcISOWeek(dateValue);
+        const formatter = new Intl.NumberFormat(undefined, defaultWeekRendererFormatOptions);
+        const manuallyLocalizedWeekNumberString = formatter.format(x.week);
+
+        expect(r.container.innerHTML).toEqual(manuallyLocalizedWeekNumberString);
+
+    });
+
+    it("should render a week number of a date value to a pure localized 1-digit string", () => {
+        const r = render(<WeekRenderer value={dateValue} pure minimumIntegerDigits={1} />);
+        const x = calcISOWeek(dateValue);
+        const formatter = new Intl.NumberFormat(undefined, { ...defaultWeekRendererFormatOptions, minimumIntegerDigits: 1 });
+        const manuallyLocalizedWeekNumberString = formatter.format(x.week);
+
+        expect(r.container.innerHTML).toEqual(manuallyLocalizedWeekNumberString);
+    });
+
+    it("should render a week number of a date value to a pure string according to a given numbering system", () => {
+        const r = render(<WeekRenderer value={dateValue} pure numberingSystem="tibt" />);
+        const x = calcISOWeek(dateValue);
+        const formatter = new Intl.NumberFormat(undefined, { ...defaultWeekRendererFormatOptions, numberingSystem: "tibt" });
+        const manuallyFormatedWeekNumberString = formatter.format(x.week);
+
+        expect(r.container.innerHTML).toEqual(manuallyFormatedWeekNumberString);
+    });
+
+
+    it("should render a week number of a date value to a pure specifically localized string with year of the week", () => {
+        const r = render(<WeekRenderer value={dateValue} displayYear pure />);
+        const x = calcISOWeek(dateValue);
+        const formatter = new Intl.NumberFormat(undefined, defaultWeekRendererFormatOptions);
+        const manuallyLocalizedWeekNumberString = `${formatter.format(x.week)}/${x.year}`;
+
+        expect(r.container.innerHTML).toEqual(manuallyLocalizedWeekNumberString);
+    });
+
+
+    it("should render an empty string when a date value is missing", () => {
+        const r = render(<WeekRenderer value={null} pure />);
+
+        expect(r.container.innerHTML).toEqual("");
+    });
+
+    it("should render correct week numbers for 'edge case' date values", () => {
+        expect(render(<WeekRenderer value={dateValue} displayYear pure />).container.innerHTML).toEqual("01/2026");
+        expect(render(<WeekRenderer value={new Date("2024-12-30T11:11:11.111Z")} displayYear pure />).container.innerHTML).toEqual("01/2025");
+        expect(render(<WeekRenderer value={new Date("2025-01-01T11:11:11.111Z")} displayYear pure />).container.innerHTML).toEqual("01/2025");
+        expect(render(<WeekRenderer value={new Date("2026-12-28T11:11:11.111Z")} displayYear pure />).container.innerHTML).toEqual("53/2026");
+        expect(render(<WeekRenderer value={new Date("2027-01-03T11:11:11.111Z")} displayYear pure />).container.innerHTML).toEqual("53/2026");
+        expect(render(<WeekRenderer value={new Date("2027-01-04T11:11:11.111Z")} displayYear pure />).container.innerHTML).toEqual("01/2027");
+        expect(render(<WeekRenderer value={new Date("2025-12-29T11:11:11.111Z")} displayYear pure />).container.innerHTML).toEqual("01/2026");
+    });
+
+    it("protected method 'getFormatedText()' should return a localized week number as string", () => {
+        class WeekRendererWrapper extends WeekRenderer {
+            public getFormatedText() {
+                return super.getFormatedText();
+            }
+        }
+        const component = new WeekRendererWrapper({ value: dateValue });
+        const automaticallyLocalizedWeekNumberString = new Intl.NumberFormat(undefined, defaultWeekRendererFormatOptions).format(calcISOWeek(dateValue).week);
+
+        expect(component.getFormatedText()).toEqual(automaticallyLocalizedWeekNumberString);
+    });
+
+});

src/components/WeekRenderer/WeekRenderer.stories.tsx

@@ -0,0 +1,69 @@
+import React from 'react';
+import { Meta, StoryObj } from '@storybook/react';
+import { WeekRenderer } from './WeekRenderer';
+import { numberingSystemLabels, numberingSystemMappings, numberingSystemOptions, RemoveKeyAttribute } from "../../../.storybook/utils";
+
+const testdate = new Date("2024-10-06T19:40:55.221Z");
+
+// +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+
+const meta = {
+  title: 'Components/WeekRenderer',
+  component: WeekRenderer,
+  argTypes: {
+    value: {
+      control: "date",
+      description: "The **value** from which the *date* part should be rendered.",
+    },
+    pure: {
+      control: "boolean",
+      description: "If **pure** is set/defined, then the component will render nothing but the 'pure' text representation of the value. Otherwise, the text representation is embeded within a *<span></span>* tag. (default: false/unset)",
+    },
+    minimumIntegerDigits: {
+      control: { type: "range", min: 1, max: 2, step: 1 },
+      description: "this parameter defines the amount of displayed digits (1 or 2) for the week number when the value is < 10. (default: 2 digits).",
+      defaultValue: undefined
+    },
+    displayYear: {
+      control: "boolean",
+      description: "Should the year corresponding to the week number be displayed (e.g. '53/2026')? (default: false/unset)"
+    },
+    numberingSystem: {
+      control: { type: "select", labels: numberingSystemLabels },
+      description: "this parameter defines the 'design' of the displayed digits. (default: unset → client numbering system)",
+      options: numberingSystemOptions,
+      mapping: numberingSystemMappings
+    }
+  },
+  parameters: {
+    docs: {
+      controls: { sort: "requiredFirst" },
+      source: { language: 'tsx', type: 'auto', transform: RemoveKeyAttribute },
+      description: { component: "The **WeekRenderer** component displays the **ISO-week number** corresponding to the input *value* of type `Date`. The displayed string is either pure or *spanned* i.e. enclosed by a *&lt;span&gt;&lt;/span&gt;* tag. Optionally, the year corresponding to the calculated week number can be disaplyed as well (e.g. '53/2026')." },
+    },
+    layout: 'centered'
+  },
+  render: RenderWeekRenderer
+} satisfies Meta<typeof WeekRenderer>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+// +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+
+function RenderWeekRenderer(args) {
+  if (typeof args.value == 'number') args.value = new Date(args.value);
+  return <WeekRenderer key={Math.random()} {...args} />
+}
+
+// +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+
+export const Playground = {
+  name: "Playground",
+  args: {
+    value: testdate,
+    pure: false,
+    displayYear: false
+  },
+  tags: ['!dev']
+} satisfies Story;

src/components/WeekRenderer/WeekRenderer.tsx

@@ -0,0 +1,62 @@
+import { AbstractRenderer, IAbstractRendererProps, ModifyValueType } from "../AbstractRenderer";
+
+
+export const defaultWeekRendererFormatOptions: Intl.NumberFormatOptions = { minimumIntegerDigits: 2, useGrouping: false };
+
+interface WeekRendererValue {
+    value: Date;
+}
+
+type ISOWeek = {
+    week: number;
+    year: number;
+}
+
+export interface IWeekRendererProps extends ModifyValueType<IAbstractRendererProps, WeekRendererValue> {
+    minimumIntegerDigits?: 1 | 2;
+    displayYear?: boolean;
+    numberingSystem?: string;
+}
+
+export class WeekRenderer extends AbstractRenderer<Date, IWeekRendererProps> {
+    protected getFormatedText(): string {
+        if (this.value) {
+
+            const options = {
+                ...defaultWeekRendererFormatOptions,
+                ... this.props.minimumIntegerDigits && { minimumIntegerDigits: this.props.minimumIntegerDigits },
+                ... this.props.numberingSystem && { numberingSystem: this.props.numberingSystem }
+            };
+            const isoWeek = calcISOWeek(this.value);
+            const formatter = new Intl.NumberFormat(undefined, options);
+            return formatter.format(isoWeek.week) + (this.props.displayYear ? "/" + formatter.format(isoWeek.year) : "");
+        } else {
+            return "";
+        }
+    }
+}
+
+// Returns the ISO calendar week corresponding to the input date.
+export function calcISOWeek(inputDate: Date): ISOWeek {
+    const purifiedDate = new Date(inputDate.getTime());
+    // Remove Time part of the Date value
+    purifiedDate.setHours(0, 0, 0, 0);
+    // Thursday in current week decides the year.
+    const thursday = purifiedDate;
+    // This is the four-digit year corresponding to the input ISO week of the date.
+    const year = calcYearOfISOCalendarWeek(thursday);
+    // January 4 is always in week 1.
+    const fourthOfJanuaryWeek = new Date(year, 0, 4);
+    // Adjust to Thursday in week 1 and count number of weeks from date to week1.
+    const week = 1 + Math.round(((thursday.getTime() - fourthOfJanuaryWeek.getTime()) / 86400000 - 3 + (fourthOfJanuaryWeek.getDay() + 6) % 7) / 7);
+    return { week, year }
+}
+
+// Returns the four-digit year corresponding to the ISO week of the date.
+function calcYearOfISOCalendarWeek(inputDate: Date): number {
+    const purifiedDate = new Date(inputDate.getTime());
+    // Thursday in current week decides the year.
+    purifiedDate.setDate(purifiedDate.getDate() + 3 - (purifiedDate.getDay() + 6) % 7);
+    // console.log("4", purifiedDate);
+    return purifiedDate.getFullYear();
+}

src/components/WeekRenderer/index.ts

@@ -0,0 +1 @@
+export * from './WeekRenderer';

src/components/introduction.mdx

@@ -2,6 +2,7 @@ import { Canvas, Source, Meta, Story } from '@storybook/blocks';
 import { DateRenderer } from "./DateRenderer";
 import { TimeRenderer } from "./TimeRenderer";
 import { DateTimeRenderer } from "./DateTimeRenderer";
+import { WeekRenderer } from "./WeekRenderer";
 import banner from '../../docs/johannes-plenio-2QUvkQTBh5s-unsplash.jpg';
 
 <style>
@@ -153,6 +154,7 @@ import banner from '../../docs/johannes-plenio-2QUvkQTBh5s-unsplash.jpg';
 </section>
 
 ### DateTimeRenderer
+
 <div className="previewoutput">
     <DateTimeRenderer value={new Date()} /><br />
     <DateTimeRenderer value={new Date()} locale="en-EN" pure /><br />
@@ -181,6 +183,42 @@ import banner from '../../docs/johannes-plenio-2QUvkQTBh5s-unsplash.jpg';
   <p>Note: the Date value passed as property to the DateTimeRenderer component should be a **UTC** date</p>
 </section>
 
+### WeekRenderer
+
+<div className="previewoutput">
+    <DateRenderer value={new Date()} /> &rarr; <WeekRenderer value={new Date()} /><br />
+    <DateRenderer value={new Date("2024-10-06T19:40:55.221Z")} /> &rarr; <WeekRenderer value={new Date("2024-10-06T19:40:55.221Z")} pure /><br />
+    <DateRenderer value={new Date("2025-12-29T11:11:11.111Z")} /> &rarr; <WeekRenderer value={new Date("2025-12-29T11:11:11.111Z")} displayYear pure /><br />
+    <DateRenderer value={new Date("2024-12-30T11:11:11.111Z")} /> &rarr; <WeekRenderer value={new Date("2024-12-30T11:11:11.111Z")} pure /><br />
+    <DateRenderer value={new Date("2025-01-01T11:11:11.111Z")} /> &rarr; <WeekRenderer value={new Date("2025-01-01T11:11:11.111Z")} displayYear pure /><br />
+    <DateRenderer value={new Date("2025-01-01T11:11:11.111Z")} /> &rarr; <WeekRenderer value={new Date("2025-01-01T11:11:11.111Z")} displayYear numberingSystem="tibt" pure /><br />
+    <DateRenderer value={new Date("2026-12-28T11:11:11.111Z")} /> &rarr; <WeekRenderer value={new Date("2026-12-28T11:11:11.111Z")} displayYear pure /><br />
+    <DateRenderer value={new Date("2027-01-03T11:11:11.111Z")} /> &rarr; <WeekRenderer value={new Date("2027-01-03T11:11:11.111Z")} displayYear pure /><br />
+    <DateRenderer value={new Date("2027-01-04T11:11:11.111Z")} /> &rarr; <WeekRenderer value={new Date("2027-01-04T11:11:11.111Z")} displayYear pure /><br />
+    <DateRenderer value={new Date("2025-12-29T11:11:11.111Z")} /> &rarr; <WeekRenderer value={new Date("2025-12-29T11:11:11.111Z")} displayYear pure /><br />
+</div>
+<section className="accordion">
+  <input type="checkbox" name="collapse2" id="preview4" tabIndex="0" />
+  <div className="handle" >
+    <label htmlFor="preview4">source code</label>
+  </div>
+  <div className="content">
+    <Source code={`
+<WeekRenderer value={new Date()} />
+<WeekRenderer value={new Date("2024-10-06T19:40:55.221Z")} pure />
+<WeekRenderer value={new Date("2025-12-29T11:11:11.111Z")} displayYear pure />
+<WeekRenderer value={new Date("2024-12-30T11:11:11.111Z")} pure />
+<WeekRenderer value={new Date("2025-01-01T11:11:11.111Z")} displayYear pure />
+<WeekRenderer value={new Date("2025-01-01T11:11:11.111Z")} displayYear numberingSystem="tibt" pure />
+<WeekRenderer value={new Date("2026-12-28T11:11:11.111Z")} displayYear pure />
+<WeekRenderer value={new Date("2027-01-03T11:11:11.111Z")} displayYear pure />
+<WeekRenderer value={new Date("2027-01-04T11:11:11.111Z")} displayYear pure />
+<WeekRenderer value={new Date("2025-12-29T11:11:11.111Z")} displayYear pure />
+    `} dark />
+  </div>
+  <p>Note: the Date value passed as property to the TimeRenderer component should be a **UTC** date</p>
+</section>
+
 <hr />
 
 <div className="right">Visit the [Github Repository](https://github.com/khatastroffik/react-text-renderer-components)</div>
@@ -194,4 +232,5 @@ https://github.com/storybookjs/storybook/discussions/16503
 https://storybook.js.org/addons/@storybook/addon-docs
 https://egghead.io/lessons/react-add-a-welcome-page-with-sequential-stories-to-a-react-storybook 
 https://keithjgrant.com/posts/2023/04/transitioning-to-height-auto/
+https://en.wikipedia.org/wiki/List_of_tz_database_time_zones
 */}

src/index.ts

@@ -3,4 +3,5 @@ export * from './components/dummy';
 export * from './components/AbstractRenderer';
 export * from './components/DateRenderer';
 export * from './components/TimeRenderer';
-export * from './components/DateTimeRenderer';
+export * from './components/DateTimeRenderer';
+export * from './components/WeekRenderer';