Tile Manager Specification

Tile Manager (Tile Layout?) Specification [Draft]

Contents

1. Overview
2. User Stories
3. Functionality
4. Test Scenarios
5. Accessibility
6. Assumptions and Limitations
7. References

Owned by

Team Name: CodeX

Developer Name: Maria Tsvyatkova, Ivaylo Barakov

Designer Name: Silvia Ivanova

Requires approval from

• Peer Developer Name | Date:
• Design Manager Name | Date:

Signed off by

• Radoslav Mirchev | Date:
• Radoslav Karaivanov | Date:

Revision History

Version	Users	Date	Notes
1	Maria Tsvyatkova	19-Sep-2024	Initial draft
1.1	Maria Tsvyatkova	09-Oct-2024	Update User Stories

1. Overview

The igc-tile-manager component enables the display of content in tiles, offering users the flexibility to rearrange and resize them in the way that best suits their needs.

Objectives

The Tile Manager provides a base tile layout behavior, managing the placement of tiles in maximized or normal state. The tiles can be sized independently of each other and used to form complex layouts. End users can reorder tiles by dragging and dropping.

Acceptance criteria

1. The Tile Manager should allow maximizing a single tile. Dragging and resizing interactions are not allowed when a tile is maximized.
2. The Tile Manager should allow tile resizing by dragging the tile's edges.
3. The Tile Manager should allow rearranging of tiles by dragging and dropping a tile.
4. The Tile Manager should support tile's header customization.
5. The Tile Manager should allow serialization of the tile layout so that it can be saved and loaded.
6. The Tile Manager should emit events on resizing, dragging, dropping and changing the state of a tile.

2. User Stories

Developer stories:

• Story 1: As a developer, I want to define N number of tiles, so that I can display many different types of information in a single layout.
• Story 2: As a developer, I want to define number columns, so that I can control the maximum number of tiles which can be displayed in a given row.
• Story 3: As a developer, I want to specify how many rows and columns a tile should span, so that I can display tiles with different sizes.
• Story 4: As a developer, I want to have an option to allow tiles' dragging only by their header, so that I can let users interact with the tile's content.
• Story 5: As a developer, I want to restrict triggering any interactions with the content itself, so that I can provide an option to drag and drop by clicking on the tile's content.
• Story 6: As a developer, I want to control the tile's state with a property, so that I can place a tile in a maximized state.
• Story 7: As a developer, I want to have an event which is emitted when a tile changes its size, so that I can easily track the size of each tile.
• Story 8: As a developer, I want to have an event which is emitted when a tile changes its state, so that I can add custom logic to react to that change.
• Story 9: As a developer, I want to have an event which is emitted when a tile is dragged, so that I can provide a custom code to highlight the currently targeted tile.
• Story 10: As a developer, I want to have an event which is emitted when a tile is dropped, so that I can validate its drop location.
• Story 11: As a developer, I want to configure the layout to use either a Slide or Swap transition when tiles are reordered via drag and drop, so that I can control the user experience of my application.
• Story 12: As a developer, I want to be able to add/remove tile with different sizes dynamically and the tiles should rearrange minimizing the empty space between them, so that I can have a compact layout.
• Story 13: As a developer, I want to be able to save the current layout, so that I can reload it when needed.
• Story 14: As a developer, I want to restrict the end user from resizing or dragging a specific tile, so that I can ensure it is always displayed as I intended.
• Story 15: As a developer, I want to have a completely customizable tile header, so that I can modify its content based on my application logic.

End-user stories:

• Story 1: As an end-user, I want to be able to resize a tile by dragging its corner, so that I can have a better view of the content.
• Story 2: As an end-user, I want to reorder tiles via drag and drop, so that I can place the information in the order I desire.
• Story 3: As an end-user, I want to see a preview of a new tile position before dropping, so that I can understand the impact of placing the tile.
• Story 4: As an end-user, I want to be able to maximize a tile with ease, so that I can better focus on its content.
• Story 5: As an end-user, I want to have the tiles rearrange themselves in new rows when I reduce the size of the layout, so that I can keep a clear view of their content.

Stories to consider for future implementation:

• Story 1: As a developer, I want to set the size and position of the maximized tile and minimized tiles list, so that I can control the arrangement of tiles in the layout. Default maximized left.
• Story 2: As a developer, I want to define the content displayed in each tile based on its current state, so that I can customize the appearance of tiles in minimized, minimized-expanded, maximized, and normal states.
• Story 3: As a developer, I want to use a custom style for the tile drag preview, so that I can provide a customized view of a tile while being dragged.
• Story 4: As an end-user, I want to be able to drill into a minimized tile without making it the maximized tile, so that I can see tile's content without changing the currently maximized tile. (This is applicable if we have both minimized and minimized-expanded states)

3. Functionality

Describe behavior, design, look and feel of the implemented feature. Always include visual mock-up

3.1. End-User Experience

Design Handoff

3.2. Developer Experience

<igc-tile-manager dragMode="slide">
    <igc-tile>
        <igc-tile-header slot="header">
            <h3 slot="title">Title 1</h3>
            <igc-icon name="home" slot="actions"></igc-icon>
        </igc-tile-header>
        
        <p>Tile 1 content</p>
    </igc-tile>
    <igc-tile maximized>
        <p>Tile 2 content</p>
    </igc-tile>
</igc-tile-manager>

3.3. Globalization/Localization

Describe any special localization requirements such as the number of localizable strings, regional formats

3.4. Keyboard Navigation

Keys	Description
Esc	Cancel the drag/resize operation and restore the tile to its original position/size.

3.5. API

IgcTileManagerComponent

Properties

Name	Attribute	Description	Type	Default value
columnCount	-	Determines the number of CSS Grid columns used to arrange the tiles. If it is less than one, as many columns as can fit will be created, with each column being at least 20px wide and able to grow to take up an equal share of the remaining space.	number	10
dragMode	-	Determines whether the tiles slide or swap on drop.	slide | swap	slide
readOnly	-	Determines whether the tiles can be interacted with.	boolean	false
tiles	-	Gets the tiles sorted by their position in the layout.	IgcTileComponent[]	[]

Methods

Name	Description	Return type	Parameters
saveLayout	Saves the current state of the tile manager.	string	-
loadLayout	Loads the previously saved state of the tile manager.	-	data: string

Events

Name	Description	Cancelable	Parameters
igcResizeStart	Emitted when tile size started changing.	true	{ tile: IgcTileComponent }
igcResizeEnd	Emitted when tile size is changed.	false	{ tile: IgcTileComponent }
igcTileDragStarted	Emitted when an owning tile begins a drag operation.	true	{ tile: IgcTileComponent }
igcTileDragOver	Emitted when a tile is dragged over another tile.	true	{ draggedTile: IgcTileComponent, hoveredTile: IgcTileComponent }
igcTileDragEnd	Emitted when a tile drag ends.	false	{ tile: IgcTileComponent }

Slots

Name	Description
(default)	Default slot for the tile manager. Any igc-tile controls should be projected here.

CSS Parts

Name	Description
base	The base wrapper of the tile manager.

IgcTileComponent

Properties

Name	Attribute	Description	Type	Default value
tileId	tile-id	Identifier of the tile. If not explicitly set, a unique one will be assigned in the format tile-<number>	string	N/A
fullscreen	fullscreen	Indicates whether the tile occupies the whole screen.	boolean	false
maximized	maximized	Indicates whether the tile occupies all available space within the layout. Dragging and resizing are not allowed when it is true.	boolean	false
colSpan	-	Specifies the number of columns the tile spans across in the layout.	number	undefined
rowSpan	-	Specifies the number of rows the tile spans across in the layout.	number	undefined
colStart	-	Specifies the starting column where the tile is placed. If it is null, the tile will be auto placed starting from the next free column.	number | null	null
rowStart	-	Specifies the starting row where the tile is placed. If it is null, the tile will be auto placed starting from the next free row.	number | null	null
disableResize	disable-resize	Disable tile resizing.	boolean	false
disableDrag	disable-drag	Disable tile dragging.	boolean	false
position	-	Gets/sets the tile's visual position in the layout. Corresponds to the CSS order property.	number	-1

Events

Name	Description	Cancelable	Parameters
igcStateChange	Emitted when the state of the tile is changed.	true	{ tile: IgcTileComponent }

Slots

Name	Description
header	A slot for the tile's header. Any igc-tile-header control should be projected here.
(default)	A slot for the tile's content.

CSS Parts

Name	Description
base	The wrapper of a tile.
drag-over	Added when a tile is dragged over the current tile.
dragging	Added when the tile is dragged.
resizing	Added when the tile is resized.
draggable	Added when disableDrag is false.
resizable	Added when disableResize is false.
fullscreen	Added to the wrapper when a tile is in fullscreen state.
header	The header wrapper of a tile.
content-container	The content wrapper of a tile.

IgcTileHeaderComponent

Slots

Name	Description
(default)	A slot for header's title.
actions	A slot for actionable items such as maximize buttons, menus, etc.

CSS Parts

Name	Description
header	The header wrapper. Wrapping the title and the actions.
title	The title of a header.
actions	The actions that could be added to the header.

4. Test Scenarios

Automation

Rendering and initialization

• passes the default WAI-ARIA automation
• is initialized with proper default state
• renders properly
• slots user provided content in the tile
• slots user provided content for tile header

Column spans

• render tile manager with correct number of children
• each tile has correct grid area (column and row span)
• row and column template style properties are properly set
• respect tile row and column start properties

Manual slot assignment

• only accepts igc-tile element
• initialize with the correct tiles in the tiles collection and light DOM
• update the light DOM when a tile is added to the tiles collection
• update the light DOM when a tile is removed from the tiles collection
• update the tiles collection when a tile is added to the light DOM
• update the tiles collection when a tile is removed from the light DOM
• update the slot when tile is added to the tiles collection
• update the slot when a tile is removed from tiles collection

Resize

• create a ghost element on resize start
• update ghost element's size during pointer move
• set proper size on the tile and remove the ghost element on resize end
• cancel resize by pressing ESC key
• prevent resizing when disableResize is true

Drag and drop

• fire the igcTileDragStarted when drag operation is started
• adjust reflected tiles positions in slide mode
• keep the same order if dropped on the same tile in slide mode
• swap the dragged tile with the drop target in swap mode
• keep the same order if dropped on the same tile in swap mode
• prevent dragging when disableDrag is true

State change behavior

• correctly fire igcTileFullscreen event
• igcTileFullscreen event is cancelable
• correctly fire igcTileMaximize event
• igcTileMaximize event is cancelable

Serialization

• serialize tiles to JSON string
• deserialize tiles from JSON string, applying all their settings

5. Accessibility

ARIA Support

RTL Support

6. Assumptions and Limitations

Assumptions	Limitation Notes

7. References

Specify all referenced external sources