Refactored to include stories and examples

Signed-off-by: Andre Wanlin <67169551+awanlin@users.noreply.github.com>

plugins/home/src/components/index.ts

@@ -16,5 +16,3 @@
 
 export { HomepageCompositionRoot } from './HomepageCompositionRoot';
 export { SettingsModal } from './SettingsModal';
-export { HeaderWorldClock } from './HeaderWorldClock';
-export type { ClockConfig } from './HeaderWorldClock';

plugins/home/src/homePageComponents/HeaderWorldClock/HeaderWorldClock.stories.tsx

@@ -0,0 +1,97 @@
+/*
+ * Copyright 2021 The Backstage Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import { Header } from '@backstage/core-components';
+import { wrapInTestApp } from '@backstage/test-utils';
+import React, { ComponentType } from 'react';
+import { ClockConfig, HeaderWorldClock } from './HeaderWorldClock';
+
+export default {
+  title: 'Plugins/Home/Components/HeaderWorldClock',
+  decorators: [(Story: ComponentType<{}>) => wrapInTestApp(<Story />)],
+};
+
+export const Default = () => {
+  const clockConfigs: ClockConfig[] = [
+    {
+      label: 'NYC',
+      timeZone: 'America/New_York',
+    },
+    {
+      label: 'UTC',
+      timeZone: 'UTC',
+    },
+    {
+      label: 'STO',
+      timeZone: 'Europe/Stockholm',
+    },
+    {
+      label: 'TYO',
+      timeZone: 'Asia/Tokyo',
+    },
+  ];
+
+  const timeFormat: Intl.DateTimeFormatOptions = {
+    hour: '2-digit',
+    minute: '2-digit',
+    hour12: true,
+  };
+
+  return (
+    <Header title="Header World Clock" pageTitleOverride="Home">
+      <HeaderWorldClock
+        clockConfigs={clockConfigs}
+        customTimeFormat={timeFormat}
+      />
+    </Header>
+  );
+};
+
+export const TwentyFourHourClocks = () => {
+  const clockConfigs: ClockConfig[] = [
+    {
+      label: 'NYC',
+      timeZone: 'America/New_York',
+    },
+    {
+      label: 'UTC',
+      timeZone: 'UTC',
+    },
+    {
+      label: 'STO',
+      timeZone: 'Europe/Stockholm',
+    },
+    {
+      label: 'TYO',
+      timeZone: 'Asia/Tokyo',
+    },
+  ];
+
+  const timeFormat: Intl.DateTimeFormatOptions = {
+    hour: '2-digit',
+    minute: '2-digit',
+    hour12: false,
+  };
+
+  return (
+    <Header title="24hr Header World Clock" pageTitleOverride="Home">
+      <HeaderWorldClock
+        clockConfigs={clockConfigs}
+        customTimeFormat={timeFormat}
+      />
+    </Header>
+  );
+};

plugins/home/src/homePageComponents/HeaderWorldClock/HeaderWorldClock.tsx

@@ -71,7 +71,37 @@ function getTimes(
   return clocks;
 }
 
-/** @public */
+/**
+ * A component to display a configurable list of clocks for various time zones.
+ *
+ * @example
+ * Here's a simple example:
+ * ```
+ * // This will give you a clock for the time zone that Stockholm is in
+ * // you can add more than one but keep in mind space may be limited
+ * const clockConfigs: ClockConfig[] = [
+ *  {
+ *    label: 'STO',
+ *    timeZone: 'Europe/Stockholm',
+ *  },
+ * ];
+ *
+ * // Setting hour12 to false will make all the clocks show in the 24hr format
+ * const timeFormat: Intl.DateTimeFormatOptions = {
+ *  hour: '2-digit',
+ *  minute: '2-digit',
+ *  hour12: false,
+ * };
+ *
+ * // Here is the component in use:
+ * <HeaderWorldClock
+ *  clockConfigs={clockConfigs}
+ *  customTimeFormat={timeFormat}
+ * />
+ * ```
+ *
+ * @public
+ */
 export const HeaderWorldClock = (props: {
   clockConfigs: ClockConfig[];
   customTimeFormat?: Intl.DateTimeFormatOptions;

plugins/home/src/homePageComponents/index.ts

@@ -16,3 +16,4 @@
 
 export * from './CompanyLogo';
 export * from './Toolkit';
+export type { ClockConfig } from './HeaderWorldClock';

plugins/home/src/index.ts

@@ -31,9 +31,10 @@ export {
   ComponentTabs,
   ComponentTab,
   WelcomeTitle,
+  HeaderWorldClock,
 } from './plugin';
-export { SettingsModal, HeaderWorldClock } from './components';
+export { SettingsModal } from './components';
 export * from './assets';
-export type { ClockConfig } from './components';
+export type { ClockConfig } from './homePageComponents';
 export { createCardExtension } from './extensions';
 export type { ComponentRenderer } from './extensions';

plugins/home/src/plugin.ts

@@ -136,3 +136,20 @@ export const HomePageStarredEntities = homePlugin.provide(
     components: () => import('./homePageComponents/StarredEntities'),
   }),
 );
+
+/**
+ * A component to display a configurable list of clocks for various time zones.
+ *
+ * @public
+ */
+export const HeaderWorldClock = homePlugin.provide(
+  createComponentExtension({
+    name: 'HeaderWorldClock',
+    component: {
+      lazy: () =>
+        import('./homePageComponents/HeaderWorldClock').then(
+          m => m.HeaderWorldClock,
+        ),
+    },
+  }),
+);