refactor: Improved API documentation & minor code clean-ups

Author: rkaraivanov

src/components/tile-manager/tile-manager.ts

@@ -27,6 +27,16 @@ import IgcTileComponent from './tile.js';
  *
  * @element igc-tile-manager
  *
+ * @slot - Default slot for the tile manager. Only `igc-tile` elements will be projected inside the CSS grid container.
+ *
+ * @csspart base - The tile manager CSS Grid container.
+ *
+ * @cssproperty --column-count - The number of columns for the tile manager. The `column-count` attribute sets this variable.
+ * @cssproperty --row-count - The number of rows for the tile manager. The `row-count` attribute sets this variable.
+ * @cssproperty --min-col-width - The minimum size of the columns in the tile-manager. The `min-column-width` attribute sets this variable.
+ * @cssproperty --min-row-height - The minimum size of the rows in the tile-manager. The `min-row-height` attribute sets this variable.
+ * @cssproperty --grid-gap - The gap size of the underlying CSS grid container. The `gap` attributes sts this variable.
+ *
  */
 @themes(all)
 export default class IgcTileManagerComponent extends LitElement {
@@ -186,7 +196,7 @@ export default class IgcTileManagerComponent extends LitElement {
   }
 
   /**
-   * Sets the gap size of the the tile manager.
+   * Sets the gap size between tiles in the tile manager.
    *
    * @attr gap
    */
@@ -261,10 +271,20 @@ export default class IgcTileManagerComponent extends LitElement {
 
   // #region Public API
 
+  /**
+   * Returns the properties of the current tile collections as a JSON payload.
+   *
+   * @remarks
+   * The content of the tiles is not serialized or saved. Only tile properties
+   * are serialized.
+   */
   public saveLayout(): string {
     return this._serializer.saveAsJSON();
   }
 
+  /**
+   * Restores a previously serialized state produced by `saveLayout`.
+   */
   public loadLayout(data: string): void {
     this._serializer.loadFromJSON(data);
   }

src/components/tile-manager/tile.ts

@@ -42,7 +42,7 @@ import { all } from './themes/tile.js';
 import { createTileDragGhost, createTileGhost } from './tile-ghost-util.js';
 import type IgcTileManagerComponent from './tile-manager.js';
 
-type IgcTileChangeState = {
+export type IgcTileChangeState = {
   tile: IgcTileComponent;
   state: boolean;
 };
@@ -75,11 +75,11 @@ export interface IgcTileComponentEventMap {
  * @fires igcTileResizeEnd - Fired when a resize operation on a tile is successfully completed.
  * @fires igcTileResizeCancel - Fired when a resize operation on a tile is canceled by the user.
  *
+ * @slot - Default slot for the tile's content.
  * @slot title - Renders the title of the tile header.
  * @slot maximize-action - Renders the maximize action element.
  * @slot fullscreen-action - Renders the fullscreen action element.
  * @slot actions - Renders items after the default actions.
- * @slot Default slot for the tile's content.
  * @slot side-adorner - Renders the side resize handle.
  * @slot corner-adorner - Renders the corner resize handle.
  * @slot bottom-adorner - Renders the bottom resize handle.
@@ -222,9 +222,11 @@ export default class IgcTileComponent extends EventEmitterMixin<
    * The number of columns the tile will span.
    *
    * @remarks
-   * Values <= 1 will be coerced to 1.
+   * When setting a value that is less than 1, it will be
+   * coerced to 1.
    *
    * @attr col-span
+   * @default 1
    */
   @property({ type: Number, attribute: 'col-span' })
   public set colSpan(value: number) {
@@ -240,9 +242,11 @@ export default class IgcTileComponent extends EventEmitterMixin<
    * The number of rows the tile will span.
    *
    * @remarks
-   * Values <= 1 will be coerced to 1.
+   * When setting a value that is less than 1, it will be
+   * coerced to 1.
    *
    * @attr row-span
+   * @default 1
    */
   @property({ type: Number, attribute: 'row-span' })
   public set rowSpan(value: number) {
@@ -318,30 +322,38 @@ export default class IgcTileComponent extends EventEmitterMixin<
   }
 
   /**
-   * Indicates whether the tile can be resized.
+   * Indicates whether to disable tile resize behavior regardless
+   * ot its tile manager parent settings.
+   *
    * @attr disable-resize
+   * @default false
    */
   @property({ type: Boolean, reflect: true, attribute: 'disable-resize' })
   public disableResize = false;
 
   /**
-   * Indicates whether the fullscreen action is displayed.
+   * Whether to disable the rendering of the tile `fullscreen-action` slot and its
+   * default fullscreen action button.
+   *
    * @attr disable-fullscreen
+   * @default false
    */
   @property({ type: Boolean, reflect: true, attribute: 'disable-fullscreen' })
   public disableFullscreen = false;
 
   /**
-   * Indicates whether the maximize action is displayed.
+   * Whether to disable the rendering of the tile `maximize-action` slot and its
+   * default maximize action button.
+   *
    * @attr disable-maximize
+   * @default false
    */
   @property({ type: Boolean, reflect: true, attribute: 'disable-maximize' })
   public disableMaximize = false;
 
   /**
    * Gets/sets the tile's visual position in the layout.
-   *
-   * Corresponds to the CSS order property.
+   * Corresponds to the CSS `order` property.
    *
    * @attr position
    */
@@ -595,21 +607,28 @@ export default class IgcTileComponent extends EventEmitterMixin<
       this.disableMaximize &&
       this.disableFullscreen;
 
+    const hasMaximizeSlot = !(this.disableMaximize || this.fullscreen);
+    const hasFullscreenSlot = !this.disableFullscreen;
+
     return html`
       <section part="header" ?hidden=${hideHeader} ${ref(this._headerRef)}>
         <header part="title">
           <slot name="title"></slot>
         </header>
         <section id="tile-actions" part="actions">
-          ${!this.disableMaximize && !this.fullscreen
-            ? html`<slot name="maximize-action"
-                >${this._renderDefaultAction('maximize')}</slot
-              >`
+          ${hasMaximizeSlot
+            ? html`
+                <slot name="maximize-action">
+                  ${this._renderDefaultAction('maximize')}
+                </slot>
+              `
             : nothing}
-          ${!this.disableFullscreen
-            ? html`<slot name="fullscreen-action"
-                >${this._renderDefaultAction('fullscreen')}</slot
-              >`
+          ${hasFullscreenSlot
+            ? html`
+                <slot name="fullscreen-action">
+                  ${this._renderDefaultAction('fullscreen')}
+                </slot>
+              `
             : nothing}
 
           <slot name="actions"></slot>

src/index.ts

@@ -120,6 +120,7 @@ export type {
   TileManagerDragMode,
   TileManagerResizeMode,
 } from './components/types.js';
+export type { IgcTileChangeState } from './components/tile-manager/tile.js';
 export type {
   DateRangeDescriptor,
   WeekDays,

stories/tile-manager.stories.ts

@@ -115,7 +115,7 @@ const metadata: Meta<IgcTileManagerComponent> = {
     },
     gap: {
       type: 'string',
-      description: 'Sets the gap size of the the tile manager.',
+      description: 'Sets the gap size between tiles in the tile manager.',
       control: 'text',
     },
   },
@@ -143,7 +143,7 @@ interface IgcTileManagerArgs {
   minColumnWidth: string;
   /** Sets the minimum height for a row unit in the tile manager. */
   minRowHeight: string;
-  /** Sets the gap size of the the tile manager. */
+  /** Sets the gap size between tiles in the tile manager. */
   gap: string;
 }
 type Story = StoryObj<IgcTileManagerArgs>;