@learncard/react 3.0.0 → 3.0.1

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@learncard/react",
-    "version": "3.0.0",
+    "version": "3.0.1",
     "description": "",
     "main": "dist/cjs",
     "module": "dist/esm",
@@ -25,13 +25,13 @@
     "author": "Learning Economy Foundation (www.learningeconomy.io)",
     "license": "MIT",
     "devDependencies": {
-        "@learncard/types": "5.23.2",
+        "@learncard/types": "5.24.0",
         "@rollup/plugin-commonjs": "^22.0.0",
         "@rollup/plugin-json": "^4.1.0",
         "@rollup/plugin-node-resolve": "^13.3.0",
-        "@storybook/addon-essentials": "8.6.18",
-        "@storybook/react-vite": "8.6.18",
-        "@storybook/test": "8.6.18",
+        "@storybook/addon-essentials": "8.6.19",
+        "@storybook/react-vite": "8.6.19",
+        "@storybook/test": "8.6.19",
         "@svgr/rollup": "^6.2.1",
         "@testing-library/jest-dom": "^5.16.4",
         "@testing-library/react": "^13.0.0",
@@ -44,7 +44,7 @@
         "dts-bundle-generator": "^6.10.0",
         "esbuild": "^0.27.1",
         "glob": "^8.0.3",
-        "happy-dom": "^20.8.9",
+        "happy-dom": "^21.0.4",
         "postcss": "^8.5.10",
         "postcss-loader": "^6.2.1",
         "rollup": "^2.71.1",
@@ -54,7 +54,7 @@
         "rollup-plugin-peer-deps-external": "^2.2.4",
         "rollup-plugin-smart-asset": "^2.1.2",
         "rollup-plugin-styles": "^4.0.0",
-        "storybook": "8.6.18",
+        "storybook": "8.6.19",
         "style-loader": "^3.3.1",
         "tailwindcss": "^4.3.3",
         "vite": "^6.4.3",
@@ -62,8 +62,8 @@
         "@tailwindcss/node": "^4.3.3"
     },
     "dependencies": {
-        "@learncard/helpers": "1.7.0",
-        "@learncard/init": "2.5.5",
+        "@learncard/helpers": "1.7.1",
+        "@learncard/init": "2.5.6",
         "date-fns": "^2.28.0",
         "numeral": "^2.0.6",
         "pretty-bytes": "^6.0.0",

package/src/components/CertificateDisplayCard/CertificateAwardDate.test.tsx

@@ -0,0 +1,67 @@
+// @vitest-environment jsdom
+import React from 'react';
+import { render, screen, cleanup } from '@testing-library/react';
+import { afterEach, describe, expect, it } from 'vitest';
+import CertificateFrontFace from './CertificateFrontFace';
+import CertificateBackFace from './CertificateBackFace';
+import MeritBadgeFrontFace from '../MeritBadgeDisplayCard/MeritBadgeFrontFace';
+import MeritBadgeBackFace from '../MeritBadgeDisplayCard/MeritBadgeBackFace';
+import { I18nProvider } from '../../i18n';
+import type { VC } from '@learncard/types';
+
+const credential = {
+    '@context': ['https://www.w3.org/ns/credentials/v2'],
+    type: ['VerifiableCredential', 'OpenBadgeCredential'],
+    issuer: { id: 'did:example:issuer', name: 'Example school' },
+    validFrom: '2026-10-26T12:00:00Z',
+    awardedDate: '2027-10-01T00:00:00Z',
+    credentialSubject: {
+        id: 'did:example:learner',
+        achievement: { name: 'Web Foundations', description: 'Completed the course.' },
+    },
+} as unknown as VC;
+
+afterEach(cleanup);
+
+describe.each([
+    ['certificate front', (value: VC) => <CertificateFrontFace credential={value} />],
+    [
+        'certificate back',
+        (value: VC) => <CertificateBackFace credential={value} verificationItems={[]} />,
+    ],
+    ['award front', (value: VC) => <MeritBadgeFrontFace credential={value} />],
+    ['award back', (value: VC) => <MeritBadgeBackFace credential={value} verificationItems={[]} />],
+] as const)('%s award date', (_, renderFace) => {
+    it('shows the mapped award day instead of the issuance day', () => {
+        render(renderFace(credential));
+        expect(screen.getByText(/^Awarded on Oct 01, 2027(?: by)?$/)).toBeTruthy();
+        expect(screen.queryByText(/Awarded on Oct 26, 2026/)).toBeNull();
+    });
+    it('retains the legacy issuance-date fallback', () => {
+        render(renderFace({ ...credential, awardedDate: undefined }));
+        expect(screen.getByText(/^Awarded on Oct 26, 2026(?: by)?$/)).toBeTruthy();
+    });
+    it('retains the issuance-date fallback when the award date is invalid', () => {
+        render(renderFace({ ...credential, awardedDate: 'not-a-date' }));
+        expect(screen.getByText(/^Awarded on Oct 26, 2026(?: by)?$/)).toBeTruthy();
+    });
+    it('omits the date for an undated draft', () => {
+        render(renderFace({ ...credential, awardedDate: undefined, validFrom: undefined }));
+        expect(screen.queryByText(/Awarded on/)).toBeNull();
+    });
+    it('resolves the award label through the host translation adapter', () => {
+        render(
+            <I18nProvider
+                locale="fr"
+                resolve={(key, params) =>
+                    key.startsWith('credential.awardedOn')
+                        ? `Décernée le ${params?.date}`
+                        : undefined
+                }
+            >
+                {renderFace(credential)}
+            </I18nProvider>
+        );
+        expect(screen.getByText('Décernée le Oct 01, 2027')).toBeTruthy();
+    });
+});

package/src/components/CertificateDisplayCard/CertificateBackFace.tsx

@@ -1,4 +1,5 @@
 import React from 'react';
+import { useT } from '../../i18n';
 import { getCategoryDarkColor, getInfoFromCredential } from '../../helpers/credential.helpers';
 import { VC, VerificationItem } from '@learncard/types';
 import {
@@ -44,8 +45,10 @@ export const CertificateBackFace: React.FC<CertificateBackFaceProps> = ({
     handleViewFrontFace,
     customLinkedCredentialsComponent,
 }) => {
+    const t = useT();
     const { createdAt, credentialSubject } = getInfoFromCredential(credential, 'MMM dd, yyyy', {
         uppercaseDate: false,
+        dateType: 'awarded',
     });
 
     const { description } = credentialSubject?.achievement ?? {};
@@ -83,13 +86,17 @@ export const CertificateBackFace: React.FC<CertificateBackFaceProps> = ({
             )}
 
             <TruncateTextBox headerText="About" text={description}>
-                <span
-                    className={`text-grayscale-600 font-poppins text-[12px] font-[600] w-full ${
-                        description ? 'pt-[10px] border-t border-solid border-grayscale-200' : ''
-                    }`}
-                >
-                    Awarded on {createdAt}
-                </span>
+                {createdAt && (
+                    <span
+                        className={`text-grayscale-600 font-poppins text-[12px] font-[600] w-full ${
+                            description
+                                ? 'pt-[10px] border-t border-solid border-grayscale-200'
+                                : ''
+                        }`}
+                    >
+                        {t('credential.awardedOn', { date: createdAt })}
+                    </span>
+                )}
             </TruncateTextBox>
 
             {criteria && <TruncateTextBox headerText="Criteria" text={criteria} />}

package/src/components/CertificateDisplayCard/CertificateFrontFace.tsx

@@ -1,4 +1,5 @@
 import React from 'react';
+import { useT } from '../../i18n';
 
 import CertificateCornerIcon from './CertificateCornerIcon';
 import CertificateImageDisplay from './CertificateImageDisplay';
@@ -68,6 +69,7 @@ export const CertificateFrontFace: React.FC<CertificateFrontFaceProps> = ({
     hideFrontFaceDetails,
     onVerifierClick,
 }) => {
+    const t = useT();
     const {
         title = '',
         createdAt,
@@ -75,7 +77,10 @@ export const CertificateFrontFace: React.FC<CertificateFrontFaceProps> = ({
         issuee: _issuee = '',
         credentialSubject,
         imageUrl,
-    } = getInfoFromCredential(credential, 'MMM dd, yyyy', { uppercaseDate: false });
+    } = getInfoFromCredential(credential, 'MMM dd, yyyy', {
+        uppercaseDate: false,
+        dateType: 'awarded',
+    });
 
     const issuee = issueeOverride || _issuee;
     const issuer = issuerOverride || _issuer;
@@ -218,7 +223,11 @@ export const CertificateFrontFace: React.FC<CertificateFrontFaceProps> = ({
                             </>
                         )}
                     </span>
-                    {!hideIssueDate && <span className="font-jacques">Awarded on {createdAt}</span>}
+                    {!hideIssueDate && createdAt && (
+                        <span className="font-jacques">
+                            {t('credential.awardedOn', { date: createdAt })}
+                        </span>
+                    )}
                 </div>
 
                 <div className="flex flex-col gap-[10px] items-center">

package/src/components/MeritBadgeDisplayCard/MeritBadgeBackFace.tsx

@@ -1,4 +1,5 @@
 import React from 'react';
+import { useT } from '../../i18n';
 import { getCategoryDarkColor, getInfoFromCredential } from '../../helpers/credential.helpers';
 import { VC, VerificationItem } from '@learncard/types';
 import {
@@ -44,8 +45,10 @@ export const MeritBadgeBackFace: React.FC<MeritBadgeBackFaceProps> = ({
     handleViewFrontFace,
     customLinkedCredentialsComponent,
 }) => {
+    const t = useT();
     const { createdAt, credentialSubject } = getInfoFromCredential(credential, 'MMM dd, yyyy', {
         uppercaseDate: false,
+        dateType: 'awarded',
     });
 
     const { description } = credentialSubject?.achievement ?? {};
@@ -83,13 +86,17 @@ export const MeritBadgeBackFace: React.FC<MeritBadgeBackFaceProps> = ({
             )}
 
             <TruncateTextBox headerText="About" text={description}>
-                <span
-                    className={`text-grayscale-600 font-poppins text-[12px] font-[600] w-full ${
-                        description ? 'pt-[10px] border-t border-solid border-grayscale-200' : ''
-                    }`}
-                >
-                    Awarded on {createdAt}
-                </span>
+                {createdAt && (
+                    <span
+                        className={`text-grayscale-600 font-poppins text-[12px] font-[600] w-full ${
+                            description
+                                ? 'pt-[10px] border-t border-solid border-grayscale-200'
+                                : ''
+                        }`}
+                    >
+                        {t('credential.awardedOn', { date: createdAt })}
+                    </span>
+                )}
             </TruncateTextBox>
 
             {criteria && <TruncateTextBox headerText="Criteria" text={criteria} />}

package/src/components/MeritBadgeDisplayCard/MeritBadgeFrontFace.tsx

@@ -1,4 +1,5 @@
 import React from 'react';
+import { useT } from '../../i18n';
 
 import MeritBadgeCornerIcon from './MeritBadgeCornerIcon';
 import MeritBadgeImageDisplay from './MeritBadgeImageDisplay';
@@ -66,6 +67,7 @@ export const MeritBadgeFrontFace: React.FC<MeritBadgeFrontFaceProps> = ({
     hideFrontFaceDetails,
     onVerifierClick,
 }) => {
+    const t = useT();
     const {
         title = '',
         createdAt,
@@ -73,7 +75,10 @@ export const MeritBadgeFrontFace: React.FC<MeritBadgeFrontFaceProps> = ({
         issuee: _issuee = '',
         credentialSubject,
         imageUrl,
-    } = getInfoFromCredential(credential, 'MMM dd, yyyy', { uppercaseDate: false });
+    } = getInfoFromCredential(credential, 'MMM dd, yyyy', {
+        uppercaseDate: false,
+        dateType: 'awarded',
+    });
 
     const issuee = issueeOverride || _issuee;
     const issuer = issuerOverride || _issuer;
@@ -205,11 +210,11 @@ export const MeritBadgeFrontFace: React.FC<MeritBadgeFrontFaceProps> = ({
                 <div className="flex flex-col w-full">
                     <div className="text-[14px] text-grayscale-900 flex flex-col items-center w-full mb-[10px]">
                         <span className="font-jacques flex gap-[5px] items-center w-full text-ellipsis whitespace-nowrap overflow-hidden justify-center">
-                            {issueeName === '0 person' ? (
-                                'Not yet awarded'
-                            ) : (
-                                <>Awarded on {createdAt} by</>
-                            )}
+                            {issueeName === '0 person'
+                                ? 'Not yet awarded'
+                                : createdAt
+                                  ? t('credential.awardedOnBy', { date: createdAt })
+                                  : t('credential.by')}
                         </span>
                     </div>
 

package/src/helpers/credential.helpers.test.ts

@@ -106,3 +106,99 @@ describe('Credential Helpers', () => {
         });
     });
 });
+
+describe('award-date formatting', () => {
+    it.each(['awarded', 'issuance'] as const)(
+        'falls back safely for a large malformed award date in %s mode',
+        dateType => {
+            const options = { uppercaseDate: false, dateType } as const;
+            const malformed = ' '.repeat(100_000);
+            expect(
+                getInfoFromCredential(
+                    { ...VC2CredentialWithValidFrom, awardedDate: malformed } as never,
+                    'MMM dd, yyyy',
+                    options
+                ).createdAt
+            ).toBe(
+                getInfoFromCredential(VC2CredentialWithValidFrom as never, 'MMM dd, yyyy', options)
+                    .createdAt
+            );
+        }
+    );
+    it.each(['2027-10-01T00:30+02', '2027-10-01T00:30+0200', '2027-10-01T00:30+02:00'])(
+        'recognizes an explicit award timezone in %s',
+        awardedDate => {
+            expect(
+                getInfoFromCredential(
+                    { ...VC2CredentialWithValidFrom, awardedDate } as never,
+                    'MMM dd, yyyy',
+                    { uppercaseDate: false, dateType: 'awarded' }
+                ).createdAt
+            ).toBe('Sep 30, 2027');
+        }
+    );
+    it.each(['20271001', '2027-10-01T00:00', '2027-10-01T00:00:00', '2027-10-01T20:00:00'])(
+        'shows a consistent calendar award day for %s',
+        awardedDate => {
+            expect(
+                getInfoFromCredential(
+                    { ...VC2CredentialWithValidFrom, awardedDate } as never,
+                    'MMM dd, yyyy',
+                    { uppercaseDate: false, dateType: 'awarded' }
+                ).createdAt
+            ).toBe('Oct 01, 2027');
+        }
+    );
+    it('uses the standard award date only when requested and retains issuance metadata', () => {
+        const credential = { ...VC2CredentialWithValidFrom, awardedDate: '2027-10-01T00:00:00Z' };
+        expect(
+            getInfoFromCredential(credential as never, 'MMM dd, yyyy', {
+                uppercaseDate: false,
+                dateType: 'awarded',
+            }).createdAt
+        ).toBe('Oct 01, 2027');
+        expect(getInfoFromCredential(credential as never).createdAt).toBe(
+            getInfoFromCredential(VC2CredentialWithValidFrom as never).createdAt
+        );
+    });
+    it('falls back for missing or invalid award dates without inventing a date for an undated draft', () => {
+        expect(
+            getInfoFromCredential(
+                { ...VC2CredentialWithValidFrom, awardedDate: 'not-a-date' } as never,
+                'MMM dd, yyyy',
+                { uppercaseDate: false, dateType: 'awarded' }
+            ).createdAt
+        ).toBe(
+            getInfoFromCredential(VC2CredentialWithValidFrom as never, 'MMM dd, yyyy', {
+                uppercaseDate: false,
+            }).createdAt
+        );
+        expect(
+            getInfoFromCredential(VC2CredentialNoDate as never, 'MMM dd, yyyy', {
+                dateType: 'awarded',
+            }).createdAt
+        ).toBe('');
+    });
+    it('keeps the UTC award day stable at a timezone boundary', () => {
+        expect(
+            getInfoFromCredential(
+                {
+                    ...VC2CredentialWithValidFrom,
+                    awardedDate: '2027-10-01T23:30:00-02:00',
+                } as never,
+                'MMM dd, yyyy',
+                { uppercaseDate: false, dateType: 'awarded' }
+            ).createdAt
+        ).toBe('Oct 02, 2027');
+    });
+});
+
+it('treats a date-only award as a UTC calendar day', () => {
+    expect(
+        getInfoFromCredential(
+            { ...VC2CredentialWithValidFrom, awardedDate: '2027-10-01' } as never,
+            'MMM dd, yyyy',
+            { uppercaseDate: false, dateType: 'awarded' }
+        ).createdAt
+    ).toBe('Oct 01, 2027');
+});

package/src/helpers/credential.helpers.tsx

@@ -1,5 +1,5 @@
 import React from 'react';
-import { format } from 'date-fns';
+import { format, isValid, parseISO } from 'date-fns';
 
 import {
     Image,
@@ -43,7 +43,9 @@ export const getImageFromProfile = (profile: Profile): string => {
 export const getInfoFromCredential = (
     credential: VC | AchievementCredential,
     dateFormat: string = 'dd MMM yyyy',
-    options: { uppercaseDate?: boolean } = { uppercaseDate: true }
+    options: { uppercaseDate?: boolean; dateType?: 'issuance' | 'awarded' } = {
+        uppercaseDate: true,
+    }
 ): CredentialInfo => {
     const { issuer, issuanceDate, validFrom } = credential;
 
@@ -57,12 +59,29 @@ export const getInfoFromCredential = (
 
     // Support both VC 2.0 (validFrom) and VC 1.0 (issuanceDate)
     // Gracefully handle missing dates
-    const dateValue = validFrom || issuanceDate;
+    const awardDateText = typeof credential.awardedDate === 'string' ? credential.awardedDate : '';
+    const awardedDate =
+        options.dateType === 'awarded' && awardDateText ? parseISO(awardDateText) : undefined;
+    const validAwardedDate = awardedDate && isValid(awardedDate) ? awardedDate : undefined;
+    const dateValue = validAwardedDate ?? (validFrom || issuanceDate);
     let createdAt = '';
 
     if (dateValue) {
         try {
-            createdAt = format(new Date(dateValue), dateFormat);
+            const date = dateValue instanceof Date ? dateValue : new Date(dateValue);
+            // Offset-less ISO values describe a calendar day. Only explicit
+            // instants need UTC conversion, matching the Details date helper.
+            // Inspect at most six suffix characters; never scan arbitrary input
+            // with a backtracking wildcard when looking for a timezone.
+            const hasAwardOffset =
+                validAwardedDate &&
+                (awardDateText.includes('T') || awardDateText.includes(' ')) &&
+                /(?:Z|[+-]\d{2}(?::?\d{2})?)$/i.test(awardDateText.slice(-6));
+            const displayDate =
+                validAwardedDate && hasAwardOffset
+                    ? new Date(date.getUTCFullYear(), date.getUTCMonth(), date.getUTCDate())
+                    : date;
+            createdAt = format(displayDate, dateFormat);
             if (options.uppercaseDate) {
                 createdAt = createdAt.toUpperCase();
             }

package/src/i18n/index.tsx

@@ -45,6 +45,8 @@ export const EN_DEFAULTS: Record<string, string> = {
     'credential.close': 'Close',
     'credential.by': 'By',
     'credential.verified': 'Verified Credential',
+    'credential.awardedOn': 'Awarded on {date}',
+    'credential.awardedOnBy': 'Awarded on {date} by',
     'verification.title': 'Credential Verifications',
     'verification.infoText':
         'Credential verifications check the cryptographic proof of digital credentials to ensure their authenticity and accuracy.',